![]() |
Arm MAP Metric Plugin Interface
Metric Plugin Interface for MAP
|
The API functions available for use by a metric plugin library. More...
System Info Functions | |
Functions that provide information about the system or the enclosing profiler. | |
int | allinea_get_logical_core_count (void) |
Returns the number of logical cores on this system. More... | |
int | allinea_get_physical_core_count (void) |
Returns the number of physical cores on this system. More... | |
int | allinea_read_config_file (const char *variable, const char *metricId, char *value, int length) |
Reads the configuration file to find the value of a variable. More... | |
const char * | allinea_get_custom_data (metric_id_t metricId) |
It returns the "customData" attribute of the "source" element from the metric definition defined in the xml file. More... | |
Error Reporting Functions | |
Functions for reporting errors encountered by either a specific metric or an entire metric plugin library. | |
void | allinea_set_plugin_error_message (plugin_id_t plugin_id, int error_code, const char *error_message) |
Reports an error that occurred in the plugin (group of metrics). More... | |
void | allinea_set_plugin_error_messagef (plugin_id_t plugin_id, int error_code, const char *error_message,...) |
Reports an error occurred in the plugin (group of metrics). More... | |
void | allinea_set_metric_error_message (metric_id_t metric_id, int error_code, const char *error_message) |
Reports an error occurred when reading a metric. More... | |
void | allinea_set_metric_error_messagef (metric_id_t metric_id, int error_code, const char *error_message,...) |
Reports an error occurred when reading a metric. More... | |
Memory management functions | |
Async signal safe replacements for memory management functions. Since metric library functions need to be async signal safe the standard libc memory management functions (such as | |
void * | allinea_safe_malloc (size_t size) |
An async-signal-safe version of malloc . More... | |
void | allinea_safe_free (void *ptr) |
An async-signal-safe version of free . More... | |
void * | allinea_safe_calloc (size_t nmemb, size_t size) |
An async-signal-safe version of calloc . More... | |
void * | allinea_safe_realloc (void *ptr, size_t size) |
An async-signal-safe version of realloc . More... | |
Standard Utility Functions | |
Replacements for common libc utility functions. Since metric library functions need to be async signal safe most standard libc functions cannot be used. In addition, even basic syscalls (such as | |
struct timespec | allinea_get_current_time (void) |
Gets the current time using the same clock as the enclosing profiler (async-signal-safe). More... | |
int | allinea_safe_close (int fd) |
Closes the file descriptor fd previously opened by allinea_safe_open (async-signal-safe). More... | |
void | allinea_safe_fprintf (int fd, const char *format,...) |
An async-signal-safe version of fprintf . More... | |
int | allinea_safe_open (const char *file, int oflags,...) |
Opens the given file for reading or writing (async-signal-safe). More... | |
void | allinea_safe_printf (const char *format,...) |
An async-signal-safe replacement for printf . More... | |
ssize_t | allinea_safe_read (int fd, void *buf, size_t count) |
Reads up to count bytes from buf to fd (async-signal-safe) More... | |
ssize_t | allinea_safe_read_all (int fd, void *buf, size_t count) |
Reads the entire contents of fd into buf (async-signal-safe). More... | |
ssize_t | allinea_safe_read_all_with_alloc (int fd, void **buf, size_t *count) |
Reads the entire contents of fd into buf (async-signal-safe). More... | |
ssize_t | allinea_safe_read_line (int fd, void *buf, size_t count) |
Reads a line from fd into buf (async-signal-safe). More... | |
void | allinea_safe_vfprintf (int fd, const char *format, va_list ap) |
An async-signal-safe version of vfprintf . More... | |
ssize_t | allinea_safe_write (int fd, const void *buf, size_t count) |
Writes up to count bytes from buf to fd (async-signal-safe). More... | |
The API functions available for use by a metric plugin library.
struct timespec allinea_get_current_time | ( | void | ) |
Gets the current time using the same clock as the enclosing profiler (async-signal-safe).
A replacement for clock_gettime
that uses the enclosing profiler-preferred system clock (i.e. CLOCK_MONOTONIC
).
const char* allinea_get_custom_data | ( | metric_id_t | metricId | ) |
It returns the "customData" attribute of the "source" element from the metric definition defined in the xml file.
metricId | metric id |
int allinea_get_logical_core_count | ( | void | ) |
Returns the number of logical cores on this system.
This count includes effective cores reported by hyperthreading.
int allinea_get_physical_core_count | ( | void | ) |
Returns the number of physical cores on this system.
This count does not include the effective cores reported when using hyperthreading.
int allinea_read_config_file | ( | const char * | variable, |
const char * | metricId, | ||
char * | value, | ||
int | length | ||
) |
Reads the configuration file to find the value of a variable.
This function returns the value of a configuration variable, or an error if the file is empty, the variable is not found or the variable is improperly declared. This function must only be called from outside of the sampler (such as in allinea_plugin_initialise and similar functions) as it is not async signal safe.
[in] | variable | The name of the configuration variable. |
[in] | metricId | The ID of the metric with the configuration file environment variable |
[out] | value | The value of the configuration variable. |
[in] | length | The length of value |
void* allinea_safe_calloc | ( | size_t | nmemb, |
size_t | size | ||
) |
An async-signal-safe version of calloc
.
Allocates size
* nmemb
bytes and zero-initialises the memory.
To be used instead of the libc calloc
.
If memory is exhausted an error is printed to stderr and the process is aborted.
Memory allocated by this function should be released by a call to allinea_safe_free(). Do not use libc free
to free memory allocated by this function.
[in] | nmemb | the number of bytes per element to allocate |
[in] | size | the number of elements to allocate |
int allinea_safe_close | ( | int | fd | ) |
Closes the file descriptor fd previously opened by allinea_safe_open (async-signal-safe).
A replacement for close
. When used in conjunction with allinea_safe_read() and allinea_safe_write() the bytes read or bytes written will not be included in the enclosing profiler's I/O accounting.
fd | The file descriptor to close. |
void allinea_safe_fprintf | ( | int | fd, |
const char * | format, | ||
... | |||
) |
An async-signal-safe version of fprintf
.
fd | The file descriptor to write to. |
format | The format string. |
... | Zero or more values to be substituted into the format string in the same manner as printf. |
void allinea_safe_free | ( | void * | ptr | ) |
An async-signal-safe version of free
.
Frees a memory region previously allocated with allinea_safe_malloc.
To be used instead of the libc free
. Do not use this function to deallocate memory blocks previously allocated by the libc malloc
.
[in,out] | ptr | A pointer to the start of the memory region to free. This should have been previously allocated with allinea_safe_malloc(), allinea_safe_realloc(), or allinea_safe_calloc(). |
void* allinea_safe_malloc | ( | size_t | size | ) |
An async-signal-safe version of malloc
.
Allocates a memory region of size bytes. To be used instead of the libc malloc
.
If memory is exhausted an error is printed to stderr and the process is aborted.
Memory allocated by this function must be released by a call to allinea_safe_free(). Do not use the libc free()
to free memory allocated by this function.
[in] | size | The number of bytes of memory to allocate. |
int allinea_safe_open | ( | const char * | file, |
int | oflags, | ||
... | |||
) |
Opens the given file for reading or writing (async-signal-safe).
A replacement for open
. When used in conjunction with allinea_safe_read() and allinea_safe_write() the bytes read or bytes written will not be included in the enclosing profiler's I/O accounting.
file | The name of the file to open (may be an absolute or relative path) |
oflags | Flags specifying how the file should be opened. Accepts all the flags that may be given to the libc open function i.e. O_RDONLY , O_WRONLY , or O_RDWR . |
void allinea_safe_printf | ( | const char * | format, |
... | |||
) |
An async-signal-safe replacement for printf
.
format | The format string. |
... | Zero or more values to be substituted into the format string in the same manner as printf. |
ssize_t allinea_safe_read | ( | int | fd, |
void * | buf, | ||
size_t | count | ||
) |
Reads up to count bytes from buf to fd (async-signal-safe)
A replacement for read
. When used in conjunction with allinea_safe_open() and allinea_safe_close(), the read bytes will be excluded from the enclosing profiler's I/O accounting.
fd | The file descriptor to read from |
buf | The buffer to read to. |
count | The maximum number of bytes to read. |
ssize_t allinea_safe_read_all | ( | int | fd, |
void * | buf, | ||
size_t | count | ||
) |
Reads the entire contents of fd into buf (async-signal-safe).
When used in conjunction with allinea_safe_open() and allinea_safe_close(), the read bytes will be excluded from the enclosing profiler's I/O accounting.
fd | The file descriptor to read from. |
buf | Buffer in which to copy the contents |
count | Size of the buffer. At most this many bytes will be written to buf. |
ssize_t allinea_safe_read_all_with_alloc | ( | int | fd, |
void ** | buf, | ||
size_t * | count | ||
) |
Reads the entire contents of fd into buf (async-signal-safe).
When used in conjunction with allinea_safe_open() and allinea_safe_close(), the read bytes will be excluded from the enclosing profiler's I/O accounting. Sufficient space for the file contents plus a terminating NUL is allocated and should be freed, using allinea_safe_free, when no longer required.
fd | The file descriptor to read from. |
buf | The pointer to when the buffer pointer should be stored. |
count | Size of the buffer allocated. |
ssize_t allinea_safe_read_line | ( | int | fd, |
void * | buf, | ||
size_t | count | ||
) |
Reads a line from fd into buf (async-signal-safe).
The final newline '\n' will be removed and a final '\0' added. When used in conjunction with allinea_safe_open() and allinea_safe_close(), the written bytes will be excluded from the enclosing profiler's I/O accounting.
Lines longer than count will be truncated.
fd | The file descriptor to read from. |
buf | Buffer in which to copy the contents |
count | Size of the buffer. At most this many bytes will be written to buf. |
void* allinea_safe_realloc | ( | void * | ptr, |
size_t | size | ||
) |
An async-signal-safe version of realloc
.
Reallocates a memory region if necessary, or allocates a new one if NULL is supplied for ptr
.
To be used instead of the libc realloc
.
If memory is exhausted an error is printed to stderr and the process is aborted.
Pointers to memory regions supplied to this function should be allocated by a call to allinea_safe_malloc(), allinea_safe_calloc() or allinea_safe_realloc().
Memory allocated by this function should be released by a call to allinea_safe_free(). Do not use libc free
to free memory allocated by this function.
[in] | ptr | the starting address of the memory region to reallocate |
[in] | size | the new minimum size to request |
size
bytes available void allinea_safe_vfprintf | ( | int | fd, |
const char * | format, | ||
va_list | ap | ||
) |
An async-signal-safe version of vfprintf
.
fd | The file descriptor to write to. |
format | The format string. |
ap | A list of arguments for format |
ssize_t allinea_safe_write | ( | int | fd, |
const void * | buf, | ||
size_t | count | ||
) |
Writes up to count bytes from buf to fd (async-signal-safe).
A replacement for write
When used in conjunction with allinea_safe_open() and allinea_safe_close(), the written bytes will be excluded from the enclosing profiler's I/O accounting.
fd | The file descriptor to write to. |
buf | The buffer to write from. |
count | The number of bytes to write. |
void allinea_set_metric_error_message | ( | metric_id_t | metric_id, |
int | error_code, | ||
const char * | error_message | ||
) |
Reports an error occurred when reading a metric.
metric_id | The id identifying the metric that has encountered an error. The appropriate value will have been passed in as an argument to the metric getter call. |
error_code | An error code that can be used to distinguish between the possible errors that may have occurred. The exact value is up to the plugin author but each error condition should have its own and unique error code. In the case of a failing libc function the libc errno (from <errno.h> ) may be appropriate, but a plugin-author-specified constant could also be used. The meaning of the possible error codes should be documented for the benefit of users of your plugin. |
error_message | A text string describing the error in a human-readable form. In the case of a failing libc function the value strerror(errno) may be appropriate, but a plugin-author-specified message could also be used. |
void allinea_set_metric_error_messagef | ( | metric_id_t | metric_id, |
int | error_code, | ||
const char * | error_message, | ||
... | |||
) |
Reports an error occurred when reading a metric.
This method does printf-style substitutions to format values inside the error message.
metric_id | The id identifying the metric that has encountered an error. The appropriate value will have been passed in as an argument to the metric getter call. |
error_code | An error code that can be used to distinguish between the possible errors that may have occurred. The exact value is up to the plugin author but each error condition should have its own and unique error code. In the case of a failing libc function the libc errno (from <errno.h> ) may be appropriate, but a plugin-author-specified constant could also be used. The meaning of the possible error codes should be documented for the benefit of users of your plugin. |
error_message | A text string describing the error in a human-readable form. In the case of a failing libc function the value strerror(errno) may be appropriate, but a plugin-author-specified message could also be used. This may include printf-style substitution characters. |
... | Zero or more values to be substituted into the error_message string. |
void allinea_set_plugin_error_message | ( | plugin_id_t | plugin_id, |
int | error_code, | ||
const char * | error_message | ||
) |
Reports an error that occurred in the plugin (group of metrics).
This method takes a plain text string as its error_message. Use allinea_set_plugin_error_messagef() instead to include specific details in the string using printf-style substitution.
This method must only be called from within allinea_plugin_initialize(), and only if the plugin library will not be able to provide its data (for example if the required interfaces are not present or supported by the system).
plugin_id | The id identifying the plugin that has encountered an error. The appropriate value will have been passed in as an argument to the allinea_plugin_initialize() call. |
error_code | An error code that can be used to distinguish between the possible errors that may have occurred. The exact value is up to the plugin author but each error condition should have its own and unique error code. In the case of a failing libc function the libc errno (from <errno.h> ) may be appropriate, but a plugin-author-specified constant could also be used. The meaning of the possible error codes should be documented for the benefit of users of your plugin. |
error_message | A text string describing the error in a human-readable form. In the case of a failing libc function the value strerror(errno) may be appropriate, but a plugin-author-specified message could also be used. |
void allinea_set_plugin_error_messagef | ( | plugin_id_t | plugin_id, |
int | error_code, | ||
const char * | error_message, | ||
... | |||
) |
Reports an error occurred in the plugin (group of metrics).
This method does printf-style substitutions to format values inside the error message.
This method must only be called from within allinea_plugin_initialize(), and only if the plugin library will not be able to provide its data (for example, if the required interfaces are not present or supported by the system).
plugin_id | The id identifying the plugin that has encountered an error. The appropriate value will have been passed in as an argument to the allinea_plugin_initialize() call. |
error_code | An error code that can be used to distinguish between the possible errors that may have occurred. The exact value is up to the plugin author but each error condition should have its own and unique error code. In the case of a failing libc function the libc errno (from <errno.h> ) may be appropriate, but a plugin-author-specified constant could also be used. The meaning of the possible error codes should be documented for the benefit of users of your plugin. |
error_message | A text string describing the error in a human-readable form. In the case of a failing libc function the value strerror(errno) may be appropriate, but a plugin-author-specified message could also be used. This may include printf-style substitution characters. |
... | Zero or more values to be substituted into the error_message string in the same manner as printf. |