Mercurial > hg > CbC > CbC_gcc

annotate gcc/doc/plugins.texi @ 158:494b0b89df80 default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
...
author Shinji KONO <kono@ie.u-ryukyu.ac.jp>
date Mon, 25 May 2020 18:13:55 +0900
parents 1830386684a0
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
145
1830386684a0 gcc-9.2.0
anatofuz
parents: 131
diff changeset
1 @c Copyright (C) 2009-2020 Free Software Foundation, Inc.
55
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
2 @c Free Software Foundation, Inc.
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
3 @c This is part of the GCC manual.
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
4 @c For copying conditions, see the file gcc.texi.
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
5
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
6 @node Plugins
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
7 @chapter Plugins
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
8 @cindex Plugins
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
9
111
kono
parents: 67
diff changeset
10 GCC plugins are loadable modules that provide extra features to the
kono
parents: 67
diff changeset
11 compiler. Like GCC itself they can be distributed in source and
kono
parents: 67
diff changeset
12 binary forms.
kono
parents: 67
diff changeset
13
kono
parents: 67
diff changeset
14 GCC plugins provide developers with a rich subset of
kono
parents: 67
diff changeset
15 the GCC API to allow them to extend GCC as they see fit.
kono
parents: 67
diff changeset
16 Whether it is writing an additional optimization pass,
kono
parents: 67
diff changeset
17 transforming code, or analyzing information, plugins
kono
parents: 67
diff changeset
18 can be quite useful.
kono
parents: 67
diff changeset
19
kono
parents: 67
diff changeset
20 @menu
kono
parents: 67
diff changeset
21 * Plugins loading:: How can we load plugins.
kono
parents: 67
diff changeset
22 * Plugin API:: The APIs for plugins.
kono
parents: 67
diff changeset
23 * Plugins pass:: How a plugin interact with the pass manager.
kono
parents: 67
diff changeset
24 * Plugins GC:: How a plugin Interact with GCC Garbage Collector.
kono
parents: 67
diff changeset
25 * Plugins description:: Giving information about a plugin itself.
kono
parents: 67
diff changeset
26 * Plugins attr:: Registering custom attributes or pragmas.
kono
parents: 67
diff changeset
27 * Plugins recording:: Recording information about pass execution.
kono
parents: 67
diff changeset
28 * Plugins gate:: Controlling which passes are being run.
kono
parents: 67
diff changeset
29 * Plugins tracking:: Keeping track of available passes.
kono
parents: 67
diff changeset
30 * Plugins building:: How can we build a plugin.
kono
parents: 67
diff changeset
31 @end menu
kono
parents: 67
diff changeset
32
kono
parents: 67
diff changeset
33 @node Plugins loading
55
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
34 @section Loading Plugins
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
35
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
36 Plugins are supported on platforms that support @option{-ldl
131
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
37 -rdynamic} as well as Windows/MinGW. They are loaded by the compiler
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
38 using @code{dlopen} or equivalent and invoked at pre-determined
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
39 locations in the compilation process.
55
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
40
111
kono
parents: 67
diff changeset
41 Plugins are loaded with
55
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
42
131
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
43 @option{-fplugin=/path/to/@var{name}.@var{ext}} @option{-fplugin-arg-@var{name}-@var{key1}[=@var{value1}]}
55
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
44
131
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
45 Where @var{name} is the plugin name and @var{ext} is the platform-specific
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
46 dynamic library extension. It should be @code{dll} on Windows/MinGW,
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
47 @code{dylib} on Darwin/Mac OS X, and @code{so} on all other platforms.
55
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
48 The plugin arguments are parsed by GCC and passed to respective
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
49 plugins as key-value pairs. Multiple plugins can be invoked by
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
50 specifying multiple @option{-fplugin} arguments.
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
51
63
b7f97abdc517 update gcc from gcc-4.5.0 to gcc-4.6
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents: 55
diff changeset
52 A plugin can be simply given by its short name (no dots or
67
f6334be47118 update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents: 63
diff changeset
53 slashes). When simply passing @option{-fplugin=@var{name}}, the plugin is
f6334be47118 update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents: 63
diff changeset
54 loaded from the @file{plugin} directory, so @option{-fplugin=@var{name}} is
131
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
55 the same as @option{-fplugin=`gcc -print-file-name=plugin`/@var{name}.@var{ext}},
63
b7f97abdc517 update gcc from gcc-4.5.0 to gcc-4.6
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents: 55
diff changeset
56 using backquote shell syntax to query the @file{plugin} directory.
55
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
57
111
kono
parents: 67
diff changeset
58 @node Plugin API
55
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
59 @section Plugin API
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
60
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
61 Plugins are activated by the compiler at specific events as defined in
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
62 @file{gcc-plugin.h}. For each event of interest, the plugin should
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
63 call @code{register_callback} specifying the name of the event and
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
64 address of the callback function that will handle that event.
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
65
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
66 The header @file{gcc-plugin.h} must be the first gcc header to be included.
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
67
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
68 @subsection Plugin license check
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
69
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
70 Every plugin should define the global symbol @code{plugin_is_GPL_compatible}
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
71 to assert that it has been licensed under a GPL-compatible license.
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
72 If this symbol does not exist, the compiler will emit a fatal error
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
73 and exit with the error message:
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
74
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
75 @smallexample
67
f6334be47118 update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents: 63
diff changeset
76 fatal error: plugin @var{name} is not licensed under a GPL-compatible license
f6334be47118 update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents: 63
diff changeset
77 @var{name}: undefined symbol: plugin_is_GPL_compatible
55
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
78 compilation terminated
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
79 @end smallexample
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
80
67
f6334be47118 update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents: 63
diff changeset
81 The declared type of the symbol should be int, to match a forward declaration
f6334be47118 update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents: 63
diff changeset
82 in @file{gcc-plugin.h} that suppresses C++ mangling. It does not need to be in
f6334be47118 update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents: 63
diff changeset
83 any allocated section, though. The compiler merely asserts that
f6334be47118 update gcc from gcc-4.6-20100522 to gcc-4.6-20110318
nobuyasu <dimolto@cr.ie.u-ryukyu.ac.jp>
parents: 63
diff changeset
84 the symbol exists in the global scope. Something like this is enough:
55
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
85
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
86 @smallexample
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
87 int plugin_is_GPL_compatible;
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
88 @end smallexample
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
89
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
90 @subsection Plugin initialization
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
91
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
92 Every plugin should export a function called @code{plugin_init} that
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
93 is called right after the plugin is loaded. This function is
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
94 responsible for registering all the callbacks required by the plugin
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
95 and do any other required initialization.
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
96
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
97 This function is called from @code{compile_file} right before invoking
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
98 the parser. The arguments to @code{plugin_init} are:
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
99
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
100 @itemize @bullet
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
101 @item @code{plugin_info}: Plugin invocation information.
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
102 @item @code{version}: GCC version.
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
103 @end itemize
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
104
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
105 The @code{plugin_info} struct is defined as follows:
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
106
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
107 @smallexample
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
108 struct plugin_name_args
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
109 @{
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
110 char *base_name; /* Short name of the plugin
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
111 (filename without .so suffix). */
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
112 const char *full_name; /* Path to the plugin as specified with
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
113 -fplugin=. */
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
114 int argc; /* Number of arguments specified with
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
115 -fplugin-arg-.... */
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
116 struct plugin_argument *argv; /* Array of ARGC key-value pairs. */
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
117 const char *version; /* Version string provided by plugin. */
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
118 const char *help; /* Help string provided by plugin. */
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
119 @}
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
120 @end smallexample
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
121
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
122 If initialization fails, @code{plugin_init} must return a non-zero
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
123 value. Otherwise, it should return 0.
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
124
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
125 The version of the GCC compiler loading the plugin is described by the
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
126 following structure:
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
127
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
128 @smallexample
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
129 struct plugin_gcc_version
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
130 @{
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
131 const char *basever;
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
132 const char *datestamp;
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
133 const char *devphase;
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
134 const char *revision;
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
135 const char *configuration_arguments;
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
136 @};
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
137 @end smallexample
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
138
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
139 The function @code{plugin_default_version_check} takes two pointers to
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
140 such structure and compare them field by field. It can be used by the
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
141 plugin's @code{plugin_init} function.
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
142
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
143 The version of GCC used to compile the plugin can be found in the symbol
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
144 @code{gcc_version} defined in the header @file{plugin-version.h}. The
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
145 recommended version check to perform looks like
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
146
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
147 @smallexample
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
148 #include "plugin-version.h"
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
149 ...
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
150
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
151 int
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
152 plugin_init (struct plugin_name_args *plugin_info,
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
153 struct plugin_gcc_version *version)
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
154 @{
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
155 if (!plugin_default_version_check (version, &gcc_version))
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
156 return 1;
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
157
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
158 @}
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
159 @end smallexample
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
160
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
161 but you can also check the individual fields if you want a less strict check.
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
162
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
163 @subsection Plugin callbacks
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
164
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
165 Callback functions have the following prototype:
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
166
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
167 @smallexample
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
168 /* The prototype for a plugin callback function.
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
169 gcc_data - event-specific data provided by GCC
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
170 user_data - plugin-specific data provided by the plug-in. */
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
171 typedef void (*plugin_callback_func)(void *gcc_data, void *user_data);
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
172 @end smallexample
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
173
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
174 Callbacks can be invoked at the following pre-determined events:
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
175
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
176
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
177 @smallexample
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
178 enum plugin_event
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
179 @{
111
kono
parents: 67
diff changeset
180 PLUGIN_START_PARSE_FUNCTION, /* Called before parsing the body of a function. */
kono
parents: 67
diff changeset
181 PLUGIN_FINISH_PARSE_FUNCTION, /* After finishing parsing a function. */
55
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
182 PLUGIN_PASS_MANAGER_SETUP, /* To hook into pass manager. */
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
183 PLUGIN_FINISH_TYPE, /* After finishing parsing a type. */
111
kono
parents: 67
diff changeset
184 PLUGIN_FINISH_DECL, /* After finishing parsing a declaration. */
55
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
185 PLUGIN_FINISH_UNIT, /* Useful for summary processing. */
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
186 PLUGIN_PRE_GENERICIZE, /* Allows to see low level AST in C and C++ frontends. */
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
187 PLUGIN_FINISH, /* Called before GCC exits. */
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
188 PLUGIN_INFO, /* Information about the plugin. */
63
b7f97abdc517 update gcc from gcc-4.5.0 to gcc-4.6
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents: 55
diff changeset
189 PLUGIN_GGC_START, /* Called at start of GCC Garbage Collection. */
b7f97abdc517 update gcc from gcc-4.5.0 to gcc-4.6
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents: 55
diff changeset
190 PLUGIN_GGC_MARKING, /* Extend the GGC marking. */
b7f97abdc517 update gcc from gcc-4.5.0 to gcc-4.6
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents: 55
diff changeset
191 PLUGIN_GGC_END, /* Called at end of GGC. */
b7f97abdc517 update gcc from gcc-4.5.0 to gcc-4.6
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents: 55
diff changeset
192 PLUGIN_REGISTER_GGC_ROOTS, /* Register an extra GGC root table. */
55
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
193 PLUGIN_ATTRIBUTES, /* Called during attribute registration */
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
194 PLUGIN_START_UNIT, /* Called before processing a translation unit. */
63
b7f97abdc517 update gcc from gcc-4.5.0 to gcc-4.6
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents: 55
diff changeset
195 PLUGIN_PRAGMAS, /* Called during pragma registration. */
55
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
196 /* Called before first pass from all_passes. */
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
197 PLUGIN_ALL_PASSES_START,
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
198 /* Called after last pass from all_passes. */
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
199 PLUGIN_ALL_PASSES_END,
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
200 /* Called before first ipa pass. */
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
201 PLUGIN_ALL_IPA_PASSES_START,
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
202 /* Called after last ipa pass. */
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
203 PLUGIN_ALL_IPA_PASSES_END,
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
204 /* Allows to override pass gate decision for current_pass. */
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
205 PLUGIN_OVERRIDE_GATE,
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
206 /* Called before executing a pass. */
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
207 PLUGIN_PASS_EXECUTION,
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
208 /* Called before executing subpasses of a GIMPLE_PASS in
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
209 execute_ipa_pass_list. */
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
210 PLUGIN_EARLY_GIMPLE_PASSES_START,
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
211 /* Called after executing subpasses of a GIMPLE_PASS in
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
212 execute_ipa_pass_list. */
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
213 PLUGIN_EARLY_GIMPLE_PASSES_END,
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
214 /* Called when a pass is first instantiated. */
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
215 PLUGIN_NEW_PASS,
111
kono
parents: 67
diff changeset
216 /* Called when a file is #include-d or given via the #line directive.
kono
parents: 67
diff changeset
217 This could happen many times. The event data is the included file path,
kono
parents: 67
diff changeset
218 as a const char* pointer. */
kono
parents: 67
diff changeset
219 PLUGIN_INCLUDE_FILE,
55
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
220
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
221 PLUGIN_EVENT_FIRST_DYNAMIC /* Dummy event used for indexing callback
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
222 array. */
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
223 @};
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
224 @end smallexample
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
225
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
226 In addition, plugins can also look up the enumerator of a named event,
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
227 and / or generate new events dynamically, by calling the function
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
228 @code{get_named_event_id}.
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
229
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
230 To register a callback, the plugin calls @code{register_callback} with
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
231 the arguments:
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
232
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
233 @itemize
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
234 @item @code{char *name}: Plugin name.
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
235 @item @code{int event}: The event code.
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
236 @item @code{plugin_callback_func callback}: The function that handles @code{event}.
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
237 @item @code{void *user_data}: Pointer to plugin-specific data.
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
238 @end itemize
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
239
111
kono
parents: 67
diff changeset
240 For the @i{PLUGIN_PASS_MANAGER_SETUP}, @i{PLUGIN_INFO}, and
kono
parents: 67
diff changeset
241 @i{PLUGIN_REGISTER_GGC_ROOTS} pseudo-events the @code{callback} should be null,
kono
parents: 67
diff changeset
242 and the @code{user_data} is specific.
kono
parents: 67
diff changeset
243
kono
parents: 67
diff changeset
244 When the @i{PLUGIN_PRAGMAS} event is triggered (with a null pointer as
kono
parents: 67
diff changeset
245 data from GCC), plugins may register their own pragmas. Notice that
kono
parents: 67
diff changeset
246 pragmas are not available from @file{lto1}, so plugins used with
kono
parents: 67
diff changeset
247 @code{-flto} option to GCC during link-time optimization cannot use
kono
parents: 67
diff changeset
248 pragmas and do not even see functions like @code{c_register_pragma} or
kono
parents: 67
diff changeset
249 @code{pragma_lex}.
55
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
250
111
kono
parents: 67
diff changeset
251 The @i{PLUGIN_INCLUDE_FILE} event, with a @code{const char*} file path as
kono
parents: 67
diff changeset
252 GCC data, is triggered for processing of @code{#include} or
kono
parents: 67
diff changeset
253 @code{#line} directives.
55
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
254
111
kono
parents: 67
diff changeset
255 The @i{PLUGIN_FINISH} event is the last time that plugins can call GCC
kono
parents: 67
diff changeset
256 functions, notably emit diagnostics with @code{warning}, @code{error}
kono
parents: 67
diff changeset
257 etc.
kono
parents: 67
diff changeset
258
kono
parents: 67
diff changeset
259
kono
parents: 67
diff changeset
260 @node Plugins pass
55
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
261 @section Interacting with the pass manager
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
262
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
263 There needs to be a way to add/reorder/remove passes dynamically. This
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
264 is useful for both analysis plugins (plugging in after a certain pass
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
265 such as CFG or an IPA pass) and optimization plugins.
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
266
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
267 Basic support for inserting new passes or replacing existing passes is
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
268 provided. A plugin registers a new pass with GCC by calling
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
269 @code{register_callback} with the @code{PLUGIN_PASS_MANAGER_SETUP}
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
270 event and a pointer to a @code{struct register_pass_info} object defined as follows
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
271
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
272 @smallexample
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
273 enum pass_positioning_ops
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
274 @{
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
275 PASS_POS_INSERT_AFTER, // Insert after the reference pass.
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
276 PASS_POS_INSERT_BEFORE, // Insert before the reference pass.
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
277 PASS_POS_REPLACE // Replace the reference pass.
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
278 @};
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
279
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
280 struct register_pass_info
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
281 @{
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
282 struct opt_pass *pass; /* New pass provided by the plugin. */
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
283 const char *reference_pass_name; /* Name of the reference pass for hooking
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
284 up the new pass. */
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
285 int ref_pass_instance_number; /* Insert the pass at the specified
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
286 instance number of the reference pass. */
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
287 /* Do it for every instance if it is 0. */
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
288 enum pass_positioning_ops pos_op; /* how to insert the new pass. */
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
289 @};
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
290
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
291
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
292 /* Sample plugin code that registers a new pass. */
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
293 int
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
294 plugin_init (struct plugin_name_args *plugin_info,
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
295 struct plugin_gcc_version *version)
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
296 @{
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
297 struct register_pass_info pass_info;
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
298
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
299 ...
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
300
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
301 /* Code to fill in the pass_info object with new pass information. */
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
302
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
303 ...
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
304
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
305 /* Register the new pass. */
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
306 register_callback (plugin_info->base_name, PLUGIN_PASS_MANAGER_SETUP, NULL, &pass_info);
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
307
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
308 ...
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
309 @}
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
310 @end smallexample
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
311
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
312
111
kono
parents: 67
diff changeset
313 @node Plugins GC
kono
parents: 67
diff changeset
314 @section Interacting with the GCC Garbage Collector
55
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
315
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
316 Some plugins may want to be informed when GGC (the GCC Garbage
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
317 Collector) is running. They can register callbacks for the
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
318 @code{PLUGIN_GGC_START} and @code{PLUGIN_GGC_END} events (for which
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
319 the callback is called with a null @code{gcc_data}) to be notified of
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
320 the start or end of the GCC garbage collection.
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
321
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
322 Some plugins may need to have GGC mark additional data. This can be
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
323 done by registering a callback (called with a null @code{gcc_data})
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
324 for the @code{PLUGIN_GGC_MARKING} event. Such callbacks can call the
111
kono
parents: 67
diff changeset
325 @code{ggc_set_mark} routine, preferably through the @code{ggc_mark} macro
55
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
326 (and conversely, these routines should usually not be used in plugins
111
kono
parents: 67
diff changeset
327 outside of the @code{PLUGIN_GGC_MARKING} event). Plugins that wish to hold
kono
parents: 67
diff changeset
328 weak references to gc data may also use this event to drop weak references when
kono
parents: 67
diff changeset
329 the object is about to be collected. The @code{ggc_marked_p} function can be
kono
parents: 67
diff changeset
330 used to tell if an object is marked, or is about to be collected. The
kono
parents: 67
diff changeset
331 @code{gt_clear_cache} overloads which some types define may also be of use in
kono
parents: 67
diff changeset
332 managing weak references.
55
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
333
145
1830386684a0 gcc-9.2.0
anatofuz
parents: 131
diff changeset
334 Some plugins may need to add extra GGC root tables, e.g.@: to handle their own
55
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
335 @code{GTY}-ed data. This can be done with the @code{PLUGIN_REGISTER_GGC_ROOTS}
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
336 pseudo-event with a null callback and the extra root table (of type @code{struct
111
kono
parents: 67
diff changeset
337 ggc_root_tab*}) as @code{user_data}. Running the
kono
parents: 67
diff changeset
338 @code{gengtype -p @var{source-dir} @var{file-list} @var{plugin*.c} ...}
kono
parents: 67
diff changeset
339 utility generates these extra root tables.
55
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
340
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
341 You should understand the details of memory management inside GCC
111
kono
parents: 67
diff changeset
342 before using @code{PLUGIN_GGC_MARKING} or @code{PLUGIN_REGISTER_GGC_ROOTS}.
55
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
343
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
344
111
kono
parents: 67
diff changeset
345 @node Plugins description
55
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
346 @section Giving information about a plugin
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
347
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
348 A plugin should give some information to the user about itself. This
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
349 uses the following structure:
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
350
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
351 @smallexample
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
352 struct plugin_info
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
353 @{
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
354 const char *version;
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
355 const char *help;
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
356 @};
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
357 @end smallexample
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
358
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
359 Such a structure is passed as the @code{user_data} by the plugin's
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
360 init routine using @code{register_callback} with the
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
361 @code{PLUGIN_INFO} pseudo-event and a null callback.
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
362
111
kono
parents: 67
diff changeset
363 @node Plugins attr
55
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
364 @section Registering custom attributes or pragmas
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
365
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
366 For analysis (or other) purposes it is useful to be able to add custom
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
367 attributes or pragmas.
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
368
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
369 The @code{PLUGIN_ATTRIBUTES} callback is called during attribute
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
370 registration. Use the @code{register_attribute} function to register
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
371 custom attributes.
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
372
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
373 @smallexample
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
374 /* Attribute handler callback */
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
375 static tree
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
376 handle_user_attribute (tree *node, tree name, tree args,
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
377 int flags, bool *no_add_attrs)
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
378 @{
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
379 return NULL_TREE;
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
380 @}
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
381
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
382 /* Attribute definition */
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
383 static struct attribute_spec user_attr =
131
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
384 @{ "user", 1, 1, false, false, false, false, handle_user_attribute, NULL @};
55
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
385
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
386 /* Plugin callback called during attribute registration.
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
387 Registered with register_callback (plugin_name, PLUGIN_ATTRIBUTES, register_attributes, NULL)
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
388 */
111
kono
parents: 67
diff changeset
389 static void
55
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
390 register_attributes (void *event_data, void *data)
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
391 @{
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
392 warning (0, G_("Callback to register attributes"));
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
393 register_attribute (&user_attr);
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
394 @}
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
395
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
396 @end smallexample
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
397
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
398
111
kono
parents: 67
diff changeset
399 The @i{PLUGIN_PRAGMAS} callback is called once during pragmas
kono
parents: 67
diff changeset
400 registration. Use the @code{c_register_pragma},
kono
parents: 67
diff changeset
401 @code{c_register_pragma_with_data},
kono
parents: 67
diff changeset
402 @code{c_register_pragma_with_expansion},
kono
parents: 67
diff changeset
403 @code{c_register_pragma_with_expansion_and_data} functions to register
kono
parents: 67
diff changeset
404 custom pragmas and their handlers (which often want to call
kono
parents: 67
diff changeset
405 @code{pragma_lex}) from @file{c-family/c-pragma.h}.
55
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
406
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
407 @smallexample
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
408 /* Plugin callback called during pragmas registration. Registered with
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
409 register_callback (plugin_name, PLUGIN_PRAGMAS,
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
410 register_my_pragma, NULL);
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
411 */
111
kono
parents: 67
diff changeset
412 static void
kono
parents: 67
diff changeset
413 register_my_pragma (void *event_data, void *data)
55
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
414 @{
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
415 warning (0, G_("Callback to register pragmas"));
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
416 c_register_pragma ("GCCPLUGIN", "sayhello", handle_pragma_sayhello);
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
417 @}
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
418 @end smallexample
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
419
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
420 It is suggested to pass @code{"GCCPLUGIN"} (or a short name identifying
111
kono
parents: 67
diff changeset
421 your plugin) as the ``space'' argument of your pragma.
kono
parents: 67
diff changeset
422
kono
parents: 67
diff changeset
423 Pragmas registered with @code{c_register_pragma_with_expansion} or
kono
parents: 67
diff changeset
424 @code{c_register_pragma_with_expansion_and_data} support
kono
parents: 67
diff changeset
425 preprocessor expansions. For example:
55
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
426
111
kono
parents: 67
diff changeset
427 @smallexample
kono
parents: 67
diff changeset
428 #define NUMBER 10
kono
parents: 67
diff changeset
429 #pragma GCCPLUGIN foothreshold (NUMBER)
kono
parents: 67
diff changeset
430 @end smallexample
55
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
431
111
kono
parents: 67
diff changeset
432 @node Plugins recording
55
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
433 @section Recording information about pass execution
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
434
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
435 The event PLUGIN_PASS_EXECUTION passes the pointer to the executed pass
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
436 (the same as current_pass) as @code{gcc_data} to the callback. You can also
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
437 inspect cfun to find out about which function this pass is executed for.
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
438 Note that this event will only be invoked if the gate check (if
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
439 applicable, modified by PLUGIN_OVERRIDE_GATE) succeeds.
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
440 You can use other hooks, like @code{PLUGIN_ALL_PASSES_START},
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
441 @code{PLUGIN_ALL_PASSES_END}, @code{PLUGIN_ALL_IPA_PASSES_START},
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
442 @code{PLUGIN_ALL_IPA_PASSES_END}, @code{PLUGIN_EARLY_GIMPLE_PASSES_START},
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
443 and/or @code{PLUGIN_EARLY_GIMPLE_PASSES_END} to manipulate global state
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
444 in your plugin(s) in order to get context for the pass execution.
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
445
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
446
111
kono
parents: 67
diff changeset
447 @node Plugins gate
55
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
448 @section Controlling which passes are being run
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
449
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
450 After the original gate function for a pass is called, its result
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
451 - the gate status - is stored as an integer.
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
452 Then the event @code{PLUGIN_OVERRIDE_GATE} is invoked, with a pointer
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
453 to the gate status in the @code{gcc_data} parameter to the callback function.
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
454 A nonzero value of the gate status means that the pass is to be executed.
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
455 You can both read and write the gate status via the passed pointer.
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
456
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
457
111
kono
parents: 67
diff changeset
458 @node Plugins tracking
55
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
459 @section Keeping track of available passes
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
460
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
461 When your plugin is loaded, you can inspect the various
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
462 pass lists to determine what passes are available. However, other
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
463 plugins might add new passes. Also, future changes to GCC might cause
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
464 generic passes to be added after plugin loading.
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
465 When a pass is first added to one of the pass lists, the event
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
466 @code{PLUGIN_NEW_PASS} is invoked, with the callback parameter
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
467 @code{gcc_data} pointing to the new pass.
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
468
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
469
111
kono
parents: 67
diff changeset
470 @node Plugins building
55
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
471 @section Building GCC plugins
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
472
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
473 If plugins are enabled, GCC installs the headers needed to build a
145
1830386684a0 gcc-9.2.0
anatofuz
parents: 131
diff changeset
474 plugin (somewhere in the installation tree, e.g.@: under
55
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
475 @file{/usr/local}). In particular a @file{plugin/include} directory
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
476 is installed, containing all the header files needed to build plugins.
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
477
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
478 On most systems, you can query this @code{plugin} directory by
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
479 invoking @command{gcc -print-file-name=plugin} (replace if needed
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
480 @command{gcc} with the appropriate program path).
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
481
63
b7f97abdc517 update gcc from gcc-4.5.0 to gcc-4.6
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents: 55
diff changeset
482 Inside plugins, this @code{plugin} directory name can be queried by
b7f97abdc517 update gcc from gcc-4.5.0 to gcc-4.6
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents: 55
diff changeset
483 calling @code{default_plugin_dir_name ()}.
b7f97abdc517 update gcc from gcc-4.5.0 to gcc-4.6
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents: 55
diff changeset
484
111
kono
parents: 67
diff changeset
485 Plugins may know, when they are compiled, the GCC version for which
kono
parents: 67
diff changeset
486 @file{plugin-version.h} is provided. The constant macros
kono
parents: 67
diff changeset
487 @code{GCCPLUGIN_VERSION_MAJOR}, @code{GCCPLUGIN_VERSION_MINOR},
kono
parents: 67
diff changeset
488 @code{GCCPLUGIN_VERSION_PATCHLEVEL}, @code{GCCPLUGIN_VERSION} are
kono
parents: 67
diff changeset
489 integer numbers, so a plugin could ensure it is built for GCC 4.7 with
kono
parents: 67
diff changeset
490 @smallexample
kono
parents: 67
diff changeset
491 #if GCCPLUGIN_VERSION != 4007
kono
parents: 67
diff changeset
492 #error this GCC plugin is for GCC 4.7
kono
parents: 67
diff changeset
493 #endif
kono
parents: 67
diff changeset
494 @end smallexample
kono
parents: 67
diff changeset
495
55
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
496 The following GNU Makefile excerpt shows how to build a simple plugin:
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
497
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
498 @smallexample
111
kono
parents: 67
diff changeset
499 HOST_GCC=g++
kono
parents: 67
diff changeset
500 TARGET_GCC=gcc
kono
parents: 67
diff changeset
501 PLUGIN_SOURCE_FILES= plugin1.c plugin2.cc
kono
parents: 67
diff changeset
502 GCCPLUGINS_DIR:= $(shell $(TARGET_GCC) -print-file-name=plugin)
kono
parents: 67
diff changeset
503 CXXFLAGS+= -I$(GCCPLUGINS_DIR)/include -fPIC -fno-rtti -O2
55
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
504
111
kono
parents: 67
diff changeset
505 plugin.so: $(PLUGIN_SOURCE_FILES)
kono
parents: 67
diff changeset
506 $(HOST_GCC) -shared $(CXXFLAGS) $^ -o $@@
55
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
507 @end smallexample
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
508
111
kono
parents: 67
diff changeset
509 A single source file plugin may be built with @code{g++ -I`gcc
kono
parents: 67
diff changeset
510 -print-file-name=plugin`/include -fPIC -shared -fno-rtti -O2 plugin.c -o
55
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
511 plugin.so}, using backquote shell syntax to query the @file{plugin}
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
512 directory.
77e2b8dfacca update it from 4.4.3 to 4.5.0
ryoma <e075725@ie.u-ryukyu.ac.jp>
parents:
diff changeset
513
131
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
514 Plugin support on Windows/MinGW has a number of limitations and
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
515 additional requirements. When building a plugin on Windows we have to
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
516 link an import library for the corresponding backend executable, for
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
517 example, @file{cc1.exe}, @file{cc1plus.exe}, etc., in order to gain
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
518 access to the symbols provided by GCC. This means that on Windows a
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
519 plugin is language-specific, for example, for C, C++, etc. If you wish
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
520 to use your plugin with multiple languages, then you will need to
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
521 build multiple plugin libraries and either instruct your users on how
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
522 to load the correct version or provide a compiler wrapper that does
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
523 this automatically.
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
524
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
525 Additionally, on Windows the plugin library has to export the
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
526 @code{plugin_is_GPL_compatible} and @code{plugin_init} symbols. If you
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
527 do not wish to modify the source code of your plugin, then you can use
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
528 the @option{-Wl,--export-all-symbols} option or provide a suitable DEF
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
529 file. Alternatively, you can export just these two symbols by decorating
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
530 them with @code{__declspec(dllexport)}, for example:
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
531
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
532 @smallexample
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
533 #ifdef _WIN32
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
534 __declspec(dllexport)
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
535 #endif
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
536 int plugin_is_GPL_compatible;
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
537
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
538 #ifdef _WIN32
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
539 __declspec(dllexport)
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
540 #endif
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
541 int plugin_init (plugin_name_args *, plugin_gcc_version *)
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
542 @end smallexample
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
543
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
544 The import libraries are installed into the @code{plugin} directory
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
545 and their names are derived by appending the @code{.a} extension to
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
546 the backend executable names, for example, @file{cc1.exe.a},
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
547 @file{cc1plus.exe.a}, etc. The following command line shows how to
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
548 build the single source file plugin on Windows to be used with the C++
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
549 compiler:
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
550
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
551 @smallexample
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
552 g++ -I`gcc -print-file-name=plugin`/include -shared -Wl,--export-all-symbols \
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
553 -o plugin.dll plugin.c `gcc -print-file-name=plugin`/cc1plus.exe.a
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
554 @end smallexample
84e7813d76e9 gcc-8.2
mir3636
parents: 111
diff changeset
555
111
kono
parents: 67
diff changeset
556 When a plugin needs to use @command{gengtype}, be sure that both
kono
parents: 67
diff changeset
557 @file{gengtype} and @file{gtype.state} have the same version as the
kono
parents: 67
diff changeset
558 GCC for which the plugin is built.