From cTuning.org

Jump to: navigation, search
Navigation: cTuning.org > CTools > ICI

Contents

"Functionality levels" of the ICI API, current and planned

Functionality list

Environment dependences

Several environment variables are used to control the behaviour of ICI from outside the binaries and the command line. These variables are

Variable Description
ICI_USE Force GCC to use ICI extensions even if no -fici was specified on the command line
ICI_VERBOSE Print informational messages about ICI actions
ICI_PLUGIN name of the plugin shared library - either a pathname, or a dynamic library name to be resolved by the dynamic loader

Global variables

None... so far.

API functions by category

Plugin management

ici_load: load and initialise a plugin

Prototype void ici_load (void)
API level FICI0
Declared in gcc/ic-framework.h
Implemented in gcc/ic-framework.c
Inputs none
Return value none
Description

Load and initialise the ICI plugin specified by the contents of environment variable ICI_PLUGIN. Exit if the plugin could not be loaded.

Prerequisites

  • ICI support in GCC must be activated, either by specifying the -fici command line flag, or by setting the environment variable USE_ICI to value 1.
  • the shared library file designated by the value of the ICI_PLUGIN variable must exist and must be readable and executable for the current user. If the value of ICI_PLUGIN does not resolve to a pathname, the dynamic linker will search for the plugin using the current value of environment variable LD_LIBRARY_PATH.

Outputs

Diagnostics message(s) explaining the reason of the failure.

See also

ici_unload

ici_unload: stop the currently loaded ICI plugin

Prototype void ici_unload (void)
API level FICI0
Declared in gcc/ici-framework.h
Implemented in gcc/ici-framework.c
Inputs none
Return value none
Description

Stops the currently loaded plugin, if any, calling the termination function of the plugin (stop()).

Prerequisites

none.

Outputs

none.

See also

ici_load

Event (callback) management

ici_register_event: register an ICI event handler

Prototype void ici_register_event (const char *name, event_func func)
API level FICI0
Declared in gcc/ic-events.h
Implemented in gcc/ic-events.c
Inputs name: name of the event
func: callback function to handle the event
Return value none
Description

Register an event handler (a callback function) to be invoked whenever the named event occurs during compilation. Trigger an internal compiler error if name is either NULL or an empty string.

Prerequisites

  • The callback function func must be a resultless function taking no arguments.
  • The name of the event (name) can be neither NULL nor an empty string.

Outputs

Informational message if name was invalid (either NULL or empty string).

See also ici_call_event

ici_call_event: trigger an ICI event handler

Prototype int ici_call_event (const char *name)
API level FICI0
Declared in gcc/ic-private.h
Implemented in gcc/ic-events.c
Inputs name: name of the event
Return value false if no matching handler was found
true otherwise.
Description

Trigger the event handler (callback function) associated with the named event. Return silently if no event named name was found.

Prerequisites

None.

Outputs

None.

See also

ici_register_event

Feature management

ici_init_features: initialise the list of features exposed by ICI

Prototype void ici_init_features (void)
API level FICI0
Declared in gcc/ic-features.h
Implemented in gcc/ic-feature-list.c
Inputs none
Return value none
Description

Build the initial set of features which are available for use by plugins. Currently, the basic set consists of:

  • two features named "first_passs" et "next_pass" which replace the original GCC mechanism for chaining compiler passes.
  • the feature named "function_name" which returns the name of the function currently being compiled by GCC.

[In addition, need at least "current_file" to enable the reporting of the name of the current file]

Prerequisites

None.

Outputs

See also

ici_get_feature

[NOT IMPLEMENTED] ici_get_available_features: get the list of features currently available in ICI

Prototype const char **ici_get_available_features (int type)
API level FICI0
Declared in gcc/ic-features.h
Implemented in gcc/ic-features.c
Inputs type: <tbd>
Return value array of strings (pointers-to-char) containing the names of features
Description

Prerequisites

Outputs

See also

ici_get_feature: get the value of an ICI feature

Prototype const void *ici_get_feature (const char *feature_name)
API level FICI0
Declared in gcc/ic-features.h
Implemented in gcc/ic-features.c
Inputs type: <tbd>
Return value NULL if feature feature_name could not be found, or

pointer to the internal opaque data of feature feature_name;
otherwise, the result of calling the callback function of feature feature_name

Description

Get the pointer to the data or the callback of feature feature_name. If the feature has a non-NULL data field, return the pointer to the internal data of the feature. If not, return the result of calling the callback function of the feature.

Return silently if the feature could not found.

Prerequisites

None.

Outputs

None.

Example 

const char **list_of_params;  /* will hold the array of compiler parameter names */
list_of_params = (const char **) ici_get_feature ("compiler_params");

See also

ici_init_features, ici_get_subfeature

ici_get_feature_size: get the size of an ICI feature

Prototype int ici_get_feature_size (const char *feature_name)
API level FICI0
Declared in gcc/ic-features.h
Implemented in gcc/ic-features.c
Inputs feature_name: name of the feature
Return value size in bytes of the data associated with feature feature_name, or -1 if the feature could not be found
Description

Get the size in bytes of the data pointed to by the data pointer of feature feature_name if the feature has a non-NULL data field.

Return -1 if the feature could not found.

Prerequisites

None.

Outputs

None.

Example 

int param_count;              /* will hold the total number of parameter names */
/* Do not forget to convert number of bytes to number of elements (pointers) in array */
param_count = ici_get_feature_size ("compiler_params") / sizeof (const char **);

See also

ici_init_features, ici_get_feature, ici_get_subfeature

ici_get_subfeature: get the value of an element of an ICI feature

Prototype const void *ici_get_subfeature (const char *feature_name, const char *subfeat_name)
API level FICI0
Declared in gcc/ic-features.h
Implemented in gcc/ic-features.c
Inputs feature_name: name of the containing feature
subfeat_name: name of the subfeature (element of containing feature)
Return value NULL if feature name could not be found, or does not contain a subfeature with name subfeat_name;

pointer to the internal opaque data of subfeature subfeat_name of feature feature_name.

Description

Get the pointer to the data of a subfeature named subfeat_name which must be an element of feature feature_name. Return NULL if feature feature_name does not exist or has no member named subfeat_name.

Prerequisites

None.

Outputs

None.

Example 

int crnt_large_function_insns;    /* store current value of large-function-insns */
crnt_large_function_insns =
  (int) ici_get_subfeature ("compiler_params", "large-function-insns");

See also

ici_init_features, ici_get_feature, ici_get_feature_size

Parameter management

ici_register_parameter: register a new ICI parameter

Prototype void

ici_register_parameter (const char *name, const void* value)

API level FICI0
Declared in gcc/ic-private.h
Implemented in gcc/ic-events.c
Inputs name: name of the parameter
value: initial value of the parameter
Return value none
Description

Define a new ICI parameter named name intialised to value. Trigger an internal compiler error (failed assertion) if name is invalid.

Prerequisites

name can be neither NULL nor an empty string.

Outputs

See also

ici_unregister_parameter, ici_get_parameter

ici_unregister_parameter: unregister a previously registered ICI parameter

Prototype void

ici_unregister_parameter (const char *name)

API level FICI0
Declared in gcc/ic-private.h
Implemented in gcc/ic-events.c
Inputs name: name of the parameter to unregister
Return value none
Description

Unregister a previously registered ICI parameter named name. Trigger an internal compiler error (failed assertion) if no parameters were registered prior to calling this function. Return silently without failure if the parameter was not found.

Prerequisites

At least one parameter must have been registered before calling this function.

Outputs

Informational message if no parameters were registered prior to calling this function.

See also

ici_register_parameter, ici_get_parameter

ici_get_parameter: get the value of an ICI parameter

Prototype const void *ici_get_parameter (const char *name)
API level FICI0
Declared in gcc/ic-events.h
Implemented in gcc/ic-events.c
Inputs name: name of the parameter
Return value NULL if the parameter was found;
otherwise, the value of parameter named name
Description

Get the value of an ICI parameter. Trigger an internal compiler error if no parameters were registered prior to calling this function.

Prerequisites

At least one parameter must have been registered prior to calling this function.

Outputs

Informative message if no parameters were registered prior to calling this function.

See also

ici_register_parameter, ici_unregister_parameter

Further reading

Sample function description

Prototype type function(inputs)
API level FICI0
Declared in somefile.h
Implemented in somefile.c
Inputs none
Return value none
Description

Prerequisites

Outputs

See also

Retrieved from "https://ctuning.org/wiki/index.php/CTools:ICI:API_Reference"
Locations of visitors to this page