![]() |
Arm MAP Metric Plugin Interface
Metric Plugin Interface for MAP
|
The functions that must be implemented by every metric plugin library. More...
Functions | |
int | allinea_plugin_cleanup (plugin_id_t plugin_id, void *data) |
Cleans a metric plugin being unloaded. More... | |
int | allinea_plugin_initialize (plugin_id_t plugin_id, void *data) |
Initialises a metric plugin. More... | |
int | mymetric_getDoubleValue (metric_id_t id, struct timespec *currentSampleTime, double *outValue) |
Example of a floating-point metric getter function. More... | |
int | mymetric_getIntValue (metric_id_t id, struct timespec *currentSampleTime, uint64_t *outValue) |
Example of an integer metric getter function. More... | |
int | start_profiling (plugin_id_t plugin_id) |
Called when the sampler is initialised. More... | |
int | stop_profiling (plugin_id_t plugin_id) |
Called after the sampler stops sampling. More... | |
The functions that must be implemented by every metric plugin library.
A metric plugin library is a small shared library that implements the functions allinea_plugin_initialize() and allinea_plugin_clean(), and is called when the shared library is loaded or unloaded. It also implements one or more functions of the form (but not necessarily of the same function name) as mymetric_getIntValue() or mymetric_getDoubleValue().
See custom1.c for an example of a metric plugin that implements this template.
See Metric Plugin API for the functions that may be called by this metric library.
See Metric Definition File for information on the format of the definition file that will inform profilers what metrics the metric plugin library may provide.
int allinea_plugin_cleanup | ( | plugin_id_t | plugin_id, |
void * | data | ||
) |
Cleans a metric plugin being unloaded.
This function must be implemented by each metric plugin library. It is called when that plugin library is unloaded. Use this function to release any held resources (open files etc). Unlike most functions used in a metric plugin library, this is not called from a signal handler. Therefore, it is safe to make general function calls and even allocate or deallocate memory using the normal libc malloc/free new/delete functions.
Note: This will be called after metric data has been extracted and transferred to the frontend. Therefore, you may not see plugin error messages set by allinea_set_plugin_error_message() or allinea_set_plugin_error_messagef().
plugin_id | Opaque handle for the metric plugin. Use this when making calls to allinea_set_plugin_error_message() or allinea_set_plugin_error_messagef() |
data | Currently unused, will always be NULL |
int allinea_plugin_initialize | ( | plugin_id_t | plugin_id, |
void * | data | ||
) |
Initialises a metric plugin.
This function must be implemented by each metric plugin library. It is called when that plugin library is loaded. Use this function to setup data structures and do one-off resource checks. Unlike most functions used in a metric plugin library this is not called from a signal handler. Therefore, it is safe to make general function calls and allocate or deallocate memory using the normal libc malloc/free new/delete functions.
If it can be determined that this metric plugin cannot function (e.g. the required information is not available on this machine) then it should call allinea_set_plugin_error_message() or allinea_set_plugin_error_messagef() to explain the situation then return -1.
plugin_id | Opaque handle for the metric plugin. Use this when making calls to allinea_set_plugin_error_message() or allinea_set_plugin_error_messagef() |
data | Currently unused, will always be NULL |
int mymetric_getDoubleValue | ( | metric_id_t | id, |
struct timespec * | currentSampleTime, | ||
double * | outValue | ||
) |
Example of a floating-point metric getter function.
An example of a getter function that returns a floating point metric value. Real getter functions must be registered with the profiler using a Metric definition file. For example, this function (if it existed) would be registered by having a <metric>
element along the lines of :
The most relevant line being the one containing functionName="mymetric_getValue"
. See Metric Definition File for more details on the format of this XML file.
[in] | id | An id used by the profiler to identify this metric. This can be used in calls to Metric Plugin API functions i.e. allinea_set_metric_error_message(). |
[in,out] | currentSampleTime | The current time. This time is acquired from a monotonic clock which reports the time elapsed from some fixed point in the past. It is unaffected by changes in the system clock. |
This is passed in from the profiler to avoid unnecessary calls to allinea_get_current_time(). If this metric is backfilled then this time is not the current time, instead it is the time at which the sample was taken and the time the sampler is now requesting a data point for.
This parameter is additionally an out parameter and may be updated with the result from a call to allinea_get_current_time() to ensure the currentSampleTime is close to the point where the metric is read. Updating currentSampleTime from any other source is undefined. In the case of a backfilled metric, currentSampleTime does not function as an out parameter and will result in an error if it is used as such. It is safe to assume that this pointer is not NULL.
[out] | outValue | The return value to be provided to the profiler. It is safe to assume that this pointer is not NULL. |
int mymetric_getIntValue | ( | metric_id_t | id, |
struct timespec * | currentSampleTime, | ||
uint64_t * | outValue | ||
) |
Example of an integer metric getter function.
An example of a getter function that returns an integer metric value. Real getter functions must be registered with the profiler using a Metric definition file. For example, this function (if it existed) would be registered by having a <metric>
element along the lines of :
The most relevant line being the one containing functionName="mymetric_getValue"
. See Metric Definition File for more details on the format of this XML file.
[in] | id | An id used by the profiler to identify this metric. This can be used in calls to Metric Plugin API functions i.e. allinea_set_metric_error_message(). |
[in,out] | currentSampleTime | The current time. This time is acquired from a monotonic clock which reports the time elapsed from some fixed point in the past. It is unaffected by changes in the system clock. |
This is passed in from the profiler to avoid unnecessary calls to allinea_get_current_time(). If this metric is backfilled then this time is not the current time, instead it is the time at which the sample was taken and the time the sampler is now requesting a data point for.
This parameter is additionally an out parameter and may be updated with the result from a call to allinea_get_current_time() to ensure the currentSampleTime is close to the point where the metric is read. Updating currentSampleTime from any other source is undefined. In the case of a backfilled metric, currentSampleTime does not function as an out parameter and will result in an error if it is used as such. It is safe to assume that this pointer is not NULL.
[out] | outValue | The return value to be provided to the profiler. It is safe to assume that this pointer is not NULL. |
int start_profiling | ( | plugin_id_t | plugin_id | ) |
Called when the sampler is initialised.
An example of a function which is called when the sampler is initialised. This callback is optional and does not need to be implemented. If this function exists it can be registered as follows.
This function does not need to be async-signal-safe as it is not called from a signal.
plugin_id | Opaque handle for the metric plugin. Use this when making calls to allinea_set_plugin_error_message() or allinea_set_plugin_error_messagef() |
int stop_profiling | ( | plugin_id_t | plugin_id | ) |
Called after the sampler stops sampling.
An example of a function which is called when the sampler finishes sampling. This callback is optional and does not need to be implemented. If this function exists it can be registered as follows.
plugin_id | Opaque handle for the metric plugin. Use this when making calls to allinea_set_plugin_error_message() or allinea_set_plugin_error_messagef() |