geopm_stats_collector.h File Reference

#include "geopm_public.h"
#include "geopm_pio.h"
#include <stddef.h>

Include dependency graph for geopm_stats_collector.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	geopm_metric_stats_s
struct	geopm_report_s

Enumerations
enum	geopm_sample_stats_e {   GEOPM_SAMPLE_TIME_TOTAL , GEOPM_SAMPLE_COUNT , GEOPM_SAMPLE_PERIOD_MEAN , GEOPM_SAMPLE_PERIOD_STD ,   GEOPM_NUM_SAMPLE_STATS }
enum	geopm_metric_stats_e {   GEOPM_METRIC_COUNT , GEOPM_METRIC_FIRST , GEOPM_METRIC_LAST , GEOPM_METRIC_MIN ,   GEOPM_METRIC_MAX , GEOPM_METRIC_MEAN , GEOPM_METRIC_STD , GEOPM_NUM_METRIC_STATS }

Functions
int GEOPM_PUBLIC	geopm_stats_collector_create (size_t num_requests, const struct geopm_request_s *requests, struct geopm_stats_collector_s **collector)
	Create a stats collector handle. More...
int GEOPM_PUBLIC	geopm_stats_collector_update (struct geopm_stats_collector_s *collector)
	Update a stat collector with new values. More...
int GEOPM_PUBLIC	geopm_stats_collector_update_count (const struct geopm_stats_collector_s *collector, size_t *update_count)
	Number of updates since last reset. More...
int GEOPM_PUBLIC	geopm_stats_collector_report_yaml (const struct geopm_stats_collector_s *collector, size_t *max_report_size, char *report_yaml)
	Create a yaml report. More...
int GEOPM_PUBLIC	geopm_stats_collector_report (const struct geopm_stats_collector_s *collector, size_t num_requests, struct geopm_report_s *report)
int GEOPM_PUBLIC	geopm_stats_collector_reset (struct geopm_stats_collector_s *collector)
	Reset statistics. More...
int GEOPM_PUBLIC	geopm_stats_collector_free (struct geopm_stats_collector_s *collector)
	Release resources associated with collector handle. More...

Enumeration Type Documentation

geopm_metric_stats_e

enum geopm_metric_stats_e

Enumerator
GEOPM_METRIC_COUNT
GEOPM_METRIC_FIRST
GEOPM_METRIC_LAST
GEOPM_METRIC_MIN
GEOPM_METRIC_MAX
GEOPM_METRIC_MEAN
GEOPM_METRIC_STD
GEOPM_NUM_METRIC_STATS

geopm_sample_stats_e

enum geopm_sample_stats_e

Enumerator
GEOPM_SAMPLE_TIME_TOTAL
GEOPM_SAMPLE_COUNT
GEOPM_SAMPLE_PERIOD_MEAN
GEOPM_SAMPLE_PERIOD_STD
GEOPM_NUM_SAMPLE_STATS

Function Documentation

geopm_stats_collector_create()

int GEOPM_PUBLIC geopm_stats_collector_create	(	size_t	num_requests,
		const struct geopm_request_s *	requests,
		struct geopm_stats_collector_s **	collector
	)

Create a stats collector handle.

Provide a list of PlatformIO signal requests and construct a stats collector object. The request list determine which statistics will be included in the generated report.

Parameters

[in]	num_requests	Number of requests in array pointed to by the request pointer
[in]	requests	Array of PlatformIO signal requests that configures the report contents
[out]	collector	Handle to the constructed StatsCollector object, must be de-allocated with geopm_stats_collector_free()

Returns

0 upon success, or error code upon failure

geopm_stats_collector_free()

int GEOPM_PUBLIC geopm_stats_collector_free

(

struct geopm_stats_collector_s *

collector

)

Release resources associated with collector handle.

Parameters

[in]

collector

Handle created with a call to geopm_stats_collector_create()

Returns

0 upon success, or error code upon failure

geopm_stats_collector_report()

int GEOPM_PUBLIC geopm_stats_collector_report	(	const struct geopm_stats_collector_s *	collector,
		size_t	num_requests,
		struct geopm_report_s *	report
	)

geopm_stats_collector_report_yaml()

int GEOPM_PUBLIC geopm_stats_collector_report_yaml	(	const struct geopm_stats_collector_s *	collector,
		size_t *	max_report_size,
		char *	report_yaml
	)

Create a yaml report.

Create a report that shows all statistics gathered by calls to geopm_stats_collector_update(). To determine the size of the report string, call with *max_report_size == 0 and report_yaml == NULL. In this case max_report_size will be updated with the required string length and zero is returned. Otherwise, if *max_report_size provided by the user is not sufficient, EINVAL is returned and the value of *max_report_size is set to the required size and report_yaml is unmodified.

Parameters

[in]	collector	Handle created with a call to geopm_stats_collector_create()
[in,out]	max_report_size	Set to the length of the report_yaml string provided by the user, set to zero to query value. If too small, will be updated with required value.
[out]	report_yaml	Generated report string allocated by the user, set to NULL to query max_report_size without error.

Returns

0 upon success, or error code upon failure

geopm_stats_collector_reset()

int GEOPM_PUBLIC geopm_stats_collector_reset

(

struct geopm_stats_collector_s *

collector

)

Reset statistics.

Called by user to zero all statistics gathered. This may be called after a call to geopm_stats_collector_report_yaml() and before the next call to geopm_stats_collector_update() so that the next report that is generated is independent of the last.

Parameters

[in]

collector

Handle created with a call to geopm_stats_collector_create()

Returns

0 upon success, or error code upon failure

geopm_stats_collector_update()

int GEOPM_PUBLIC geopm_stats_collector_update

(

struct geopm_stats_collector_s *

collector

)

Update a stat collector with new values.

User is expected to call PlatformIO::read_batch() prior to calling this interface. The sampled values will be used to update the report statistics.

Parameters

[in]

collector

Handle created with a call to geopm_stats_collector_create()

Returns

0 upon success, or error code upon failure

geopm_stats_collector_update_count()

int GEOPM_PUBLIC geopm_stats_collector_update_count	(	const struct geopm_stats_collector_s *	collector,
		size_t *	update_count
	)

Number of updates since last reset.

Sets update_count to the number of times that the geopm_stats_collector_update() function has been called on the collector object since it was created, or since the last call to geopm_stats_collector_reset().

Parameters

[in]	collector	Handle created with a call to geopm_stats_collector_create()
[out]	update_count	Set to the number of updates upon successful completion

Returns

0 upon success, or error code upon failure