call @code{register_callback} specifying the name of the event and
address of the callback function that will handle that event.
+The header @file{gcc-plugin.h} must be the first gcc header to be included.
+
+@subsection Plugin license check
+
+Every plugin should define the global symbol @code{plugin_is_GPL_compatible}
+to assert that it has been licensed under a GPL-compatible license.
+If this symbol does not exist, the compiler will emit a fatal error
+and exit with the error message:
+
+@smallexample
+fatal error: plugin <name> is not licensed under a GPL-compatible license
+<name>: undefined symbol: plugin_is_GPL_compatible
+compilation terminated
+@end smallexample
+
+The type of the symbol is irrelevant. The compiler merely asserts that
+it exists in the global scope. Something like this is enough:
+
+@smallexample
+int plugin_is_GPL_compatible;
+@end smallexample
+
@subsection Plugin initialization
Every plugin should export a function called @code{plugin_init} that
PLUGIN_GGC_MARKING, /* Extend the GGC marking. */
PLUGIN_GGC_END, /* Called at end of GGC. */
PLUGIN_REGISTER_GGC_ROOTS, /* Register an extra GGC root table. */
+ PLUGIN_REGISTER_GGC_CACHES, /* Register an extra GGC cache table. */
PLUGIN_ATTRIBUTES, /* Called during attribute registration */
+ PLUGIN_START_UNIT, /* Called before processing a translation unit. */
PLUGIN_EVENT_LAST /* Dummy event used for indexing callback
array. */
@};
@item @code{void *user_data}: Pointer to plugin-specific data.
@end itemize
-For the PLUGIN_PASS_MANAGER_SETUP, PLUGIN_INFO, and
-PLUGIN_REGISTER_GGC_ROOTS pseudo-events the @code{callback} should be
+For the PLUGIN_PASS_MANAGER_SETUP, PLUGIN_INFO, PLUGIN_REGISTER_GGC_ROOTS
+and PLUGIN_REGISTER_GGC_CACHES pseudo-events the @code{callback} should be
null, and the @code{user_data} is specific.
@section Interacting with the pass manager
Basic support for inserting new passes or replacing existing passes is
provided. A plugin registers a new pass with GCC by calling
@code{register_callback} with the @code{PLUGIN_PASS_MANAGER_SETUP}
-event and a pointer to a @code{struct plugin_pass} object defined as follows
+event and a pointer to a @code{struct register_pass_info} object defined as follows
@smallexample
enum pass_positioning_ops
PASS_POS_REPLACE // Replace the reference pass.
@};
-struct plugin_pass
+struct register_pass_info
@{
struct opt_pass *pass; /* New pass provided by the plugin. */
const char *reference_pass_name; /* Name of the reference pass for hooking
plugin_init (struct plugin_name_args *plugin_info,
struct plugin_gcc_version *version)
@{
- struct plugin_pass pass_info;
+ struct register_pass_info pass_info;
...
done by registering a callback (called with a null @code{gcc_data})
for the @code{PLUGIN_GGC_MARKING} event. Such callbacks can call the
@code{ggc_set_mark} routine, preferably thru the @code{ggc_mark} macro
-(and conversly, these routines should usually not be used in plugins
-outside of the @code{PLUGIN_GGC_MARKING} event).
-
-Some plugins may need to add extra GGC root tables, e.g. to handle
-their own @code{GTY}-ed data. This can be done with the
-@code{PLUGIN_REGISTER_GGC_ROOTS} pseudo-event with a null callback and the
-extra root table as @code{user_data}.
+(and conversely, these routines should usually not be used in plugins
+outside of the @code{PLUGIN_GGC_MARKING} event).
+
+Some plugins may need to add extra GGC root tables, e.g. to handle their own
+@code{GTY}-ed data. This can be done with the @code{PLUGIN_REGISTER_GGC_ROOTS}
+pseudo-event with a null callback and the extra root table (of type @code{struct
+ggc_root_tab*}) as @code{user_data}. Plugins that want to use the
+@code{if_marked} hash table option can add the extra GGC cache tables generated
+by @code{gengtype} using the @code{PLUGIN_REGISTER_GGC_CACHES} pseudo-event with
+a null callback and the extra cache table (of type @code{struct ggc_cache_tab*})
+as @code{user_data}. Running the @code{gengtype -p @var{source-dir}
+@var{file-list} @var{plugin*.c} ...} utility generates these extra root tables.
You should understand the details of memory management inside GCC
-before using @code{PLUGIN_GGC_MARKING} or
-@code{PLUGIN_REGISTER_GGC_ROOTS}.
+before using @code{PLUGIN_GGC_MARKING}, @code{PLUGIN_REGISTER_GGC_ROOTS}
+or @code{PLUGIN_REGISTER_GGC_CACHES}.
@section Giving information about a plugin
@}
@end smallexample
+
+
+@section Building GCC plugins
+
+If plugins are enabled, GCC installs the headers needed to build a
+plugin (somehwere in the installation tree, e.g. under
+@file{/usr/local}). In particular a @file{plugin/include} directory
+is installed, containing all the header files needed to build plugins.
+
+On most systems, you can query this @code{plugin} directory by
+invoking @command{gcc -print-file-name=plugin} (replace if needed
+@command{gcc} with the appropriate program path).
+
+The following GNU Makefile excerpt shows how to build a simple plugin:
+
+@smallexample
+GCC=gcc
+PLUGIN_SOURCE_FILES= plugin1.c plugin2.c
+PLUGIN_OBJECT_FILES= $(patsubst %.c,%.o,$(PLUGIN_SOURCE_FILES))
+GCCPLUGINS_DIR:= $(shell $(GCC) -print-file-name=plugin)
+CFLAGS+= -I$(GCCPLUGINS_DIR)/include -fPIC -O2
+
+plugin.so: $(PLUGIN_OBJECT_FILES)
+ $(GCC) -shared $^ -o $@@
+@end smallexample
+
+A single source file plugin may be built with @code{gcc -I`gcc
+-print-file-name=plugin`/include -fPIC -shared -O2 plugin.c -o
+plugin.so}, using backquote shell syntax to query the @file{plugin}
+directory.
+
+Plugins needing to use @command{gengtype} require a GCC build
+directory for the same version of GCC that they will be linked
+against.
OSDN Git Service
