IOGroup that provides signals and controls based on MSRs. More...

#include <MSRIOGroup.hpp>

Inheritance diagram for geopm::MSRIOGroup:

Collaboration diagram for geopm::MSRIOGroup:

Public Types
enum	m_cpuid_e { M_CPUID_SNB = 0x62D , M_CPUID_IVT = 0x63E , M_CPUID_HSX = 0x63F , M_CPUID_BDX = 0x64F , M_CPUID_KNL = 0x657 , M_CPUID_SKX = 0x655 , M_CPUID_ICX = 0x66A , M_CPUID_SPR = 0x68F }

Public Types inherited from geopm::IOGroup
enum	m_units_e { M_UNITS_NONE , M_UNITS_SECONDS , M_UNITS_HERTZ , M_UNITS_WATTS , M_UNITS_JOULES , M_UNITS_CELSIUS , M_UNITS_AMPERES , M_UNITS_VOLTS , M_NUM_UNITS }

enum	m_signal_behavior_e { M_SIGNAL_BEHAVIOR_CONSTANT , M_SIGNAL_BEHAVIOR_MONOTONE , M_SIGNAL_BEHAVIOR_VARIABLE , M_SIGNAL_BEHAVIOR_LABEL , M_NUM_SIGNAL_BEHAVIOR }
	Description of the runtime behavior of a signal. More...

Public Member Functions
	MSRIOGroup ()=delete

	MSRIOGroup (bool use_msr_safe)

	MSRIOGroup (const PlatformTopo &platform_topo, std::shared_ptr< MSRIO > msrio, std::shared_ptr< Cpuid > cpuid, std::shared_ptr< SaveControl > save_control)

virtual	~MSRIOGroup ()=default

std::set< std::string >	signal_names (void) const override
	Returns the names of all signals provided by the IOGroup. More...

std::set< std::string >	control_names (void) const override
	Returns the names of all controls provided by the IOGroup. More...

bool	is_valid_signal (const std::string &signal_name) const override
	Test if signal_name refers to a signal supported by the group. More...

bool	is_valid_control (const std::string &control_name) const override
	Test if control_name refers to a control supported by the group. More...

int	signal_domain_type (const std::string &signal_name) const override
	Query the domain for a named signal. More...

int	control_domain_type (const std::string &control_name) const override
	Query the domain for a named control. More...

int	push_signal (const std::string &signal_name, int domain_type, int domain_idx) override
	Add a signal to the list of signals that is read by read_batch() and sampled by sample(). More...

int	push_control (const std::string &control_name, int domain_type, int domain_idx) override
	Add a control to the list of controls that is written by write_batch() and configured with adjust(). More...

void	read_batch (void) override
	Read all pushed signals from the platform so that the next call to sample() will reflect the updated data. More...

void	write_batch (void) override
	Write all of the pushed controls so that values previously given to adjust() are written to the platform. More...

double	sample (int sample_idx) override
	Retrieve signal value from data read by last call to read_batch() for a particular signal previously pushed with push_signal(). More...

void	adjust (int control_idx, double setting) override
	Adjust a setting for a particular control that was previously pushed with push_control(). This adjustment will be written to the platform on the next call to write_batch(). More...

double	read_signal (const std::string &signal_name, int domain_type, int domain_idx) override
	Read from platform and interpret into SI units a signal given its name and domain. Does not modify the values stored by calling read_batch(). More...

void	write_control (const std::string &control_name, int domain_type, int domain_idx, double setting) override
	Interpret the setting and write setting to the platform. Does not modify the values stored by calling adjust(). More...

void	save_control (void) override
	Save the state of all controls so that any subsequent changes made through the IOGroup can be undone with a call to the restore() method. More...

void	restore_control (void) override
	Restore all controls to values recorded in previous call to the save() method. More...

std::function< double(const std::vector< double > &)>	agg_function (const std::string &signal_name) const override
	Return a function that should be used when aggregating the given signal. More...

std::function< std::string(double)>	format_function (const std::string &signal_name) const override
	Returns a function that can be used to convert a signal of the given name into a printable string. May be one of the IOGroup::format_*() static methods, or another function. More...

std::string	signal_description (const std::string &signal_name) const override
	Returns a description of the signal. This string can be used by tools to generate help text for users of the IOGroup. More...

std::string	control_description (const std::string &control_name) const override
	Returns a description of the control. This string can be used by tools to generate help text for users of the IOGroup. More...

int	signal_behavior (const std::string &signal_name) const override
	Returns a hint about how a signal will change as a function of time. More...

void	save_control (const std::string &save_path) override

void	restore_control (const std::string &save_path) override

std::string	name (void) const override
	Get the IOGroup name. More...

void	parse_json_msrs (const std::string &str)
	Parse a JSON string and add any raw MSRs and fields as available signals and controls. More...

Public Member Functions inherited from geopm::IOGroup
	IOGroup ()=default

virtual	~IOGroup ()=default

Static Public Member Functions
static std::string	msr_allowlist (int cpuid)
	Fill string with the msr-safe allowlist file contents reflecting all known MSRs for the specified platform. More...

static std::string	msr_allowlist (int cpuid, const PlatformTopo &topo, std::shared_ptr< MSRIO > msrio)

static int	cpuid (void)
	DEPRECATED Get the cpuid of the current platform. More...

static std::string	plugin_name (void)

static std::unique_ptr< IOGroup >	make_plugin (void)

static std::unique_ptr< IOGroup >	make_plugin_safe (void)

Static Public Member Functions inherited from geopm::IOGroup
static std::vector< std::string >	iogroup_names (void)

static std::unique_ptr< IOGroup >	make_unique (const std::string &iogroup_name)

static m_units_e	string_to_units (const std::string &str)
	Convert a string to the corresponding m_units_e value. More...

static std::string	units_to_string (int)
	Convert the m_units_e value to the corresponding string. More...

static m_signal_behavior_e	string_to_behavior (const std::string &str)
	Convert a string to the corresponding m_signal_behavior_e value. More...

Additional Inherited Members
Static Public Attributes inherited from geopm::IOGroup
static const std::string	M_PLUGIN_PREFIX = "libgeopmiogroup_"

Detailed Description

IOGroup that provides signals and controls based on MSRs.

Member Enumeration Documentation

◆ m_cpuid_e

enum geopm::MSRIOGroup::m_cpuid_e

Enumerator
M_CPUID_SNB
M_CPUID_IVT
M_CPUID_HSX
M_CPUID_BDX
M_CPUID_KNL
M_CPUID_SKX
M_CPUID_ICX
M_CPUID_SPR

Constructor & Destructor Documentation

◆ MSRIOGroup() [1/3]

geopm::MSRIOGroup::MSRIOGroup ( )

delete

◆ MSRIOGroup() [2/3]

geopm::MSRIOGroup::MSRIOGroup ( bool use_msr_safe )

◆ MSRIOGroup() [3/3]

geopm::MSRIOGroup::MSRIOGroup	(	const PlatformTopo &	platform_topo,
		std::shared_ptr< MSRIO >	msrio,
		std::shared_ptr< Cpuid >	cpuid,
		std::shared_ptr< SaveControl >	save_control
	)

◆ ~MSRIOGroup()

virtual geopm::MSRIOGroup::~MSRIOGroup ( )

virtualdefault

Member Function Documentation

◆ adjust()

void geopm::MSRIOGroup::adjust	(	int	control_idx,
		double	setting
	)

overridevirtual

Adjust a setting for a particular control that was previously pushed with push_control(). This adjustment will be written to the platform on the next call to write_batch().

Parameters

[in]	control_idx	The index returned by previous call to push_control().
[in]	setting	Value of the control in SI units.

Implements geopm::IOGroup.

◆ agg_function()

std::function< double(const std::vector< double > &)> geopm::MSRIOGroup::agg_function ( const std::string & signal_name ) const

overridevirtual

Return a function that should be used when aggregating the given signal.

Parameters

[in] signal_name Name of the signal.

Implements geopm::IOGroup.

◆ control_description()

std::string geopm::MSRIOGroup::control_description ( const std::string & control_name ) const

overridevirtual

Returns a description of the control. This string can be used by tools to generate help text for users of the IOGroup.

Implements geopm::IOGroup.

◆ control_domain_type()

int geopm::MSRIOGroup::control_domain_type ( const std::string & control_name ) const

overridevirtual

Query the domain for a named control.

Parameters

[in] control_name Name of the control to query.

Returns: One of the PlatformTopo::m_domain_e enum values.

Implements geopm::IOGroup.

◆ control_names()

std::set< std::string > geopm::MSRIOGroup::control_names ( void ) const

overridevirtual

Returns the names of all controls provided by the IOGroup.

Implements geopm::IOGroup.

◆ cpuid()

int geopm::MSRIOGroup::cpuid ( void )

static

DEPRECATED Get the cpuid of the current platform.

◆ format_function()

std::function< std::string(double)> geopm::MSRIOGroup::format_function ( const std::string & signal_name ) const

overridevirtual

Returns a function that can be used to convert a signal of the given name into a printable string. May be one of the IOGroup::format_*() static methods, or another function.

Reimplemented from geopm::IOGroup.

◆ is_valid_control()

bool geopm::MSRIOGroup::is_valid_control ( const std::string & control_name ) const

overridevirtual

Test if control_name refers to a control supported by the group.

Parameters

[in] control_name Name of control to test.

Returns: True if control is supported, false otherwise.

Implements geopm::IOGroup.

◆ is_valid_signal()

bool geopm::MSRIOGroup::is_valid_signal ( const std::string & signal_name ) const

overridevirtual

Test if signal_name refers to a signal supported by the group.

Parameters

[in] signal_name Name of signal to test.

Returns: True if signal is supported, false otherwise.

Implements geopm::IOGroup.

◆ make_plugin()

std::unique_ptr< IOGroup > geopm::MSRIOGroup::make_plugin ( void )

static

◆ make_plugin_safe()

std::unique_ptr< IOGroup > geopm::MSRIOGroup::make_plugin_safe ( void )

static

◆ msr_allowlist() [1/2]

std::string geopm::MSRIOGroup::msr_allowlist ( int cpuid )

static

Fill string with the msr-safe allowlist file contents reflecting all known MSRs for the specified platform.

Parameters

cpuid [in] The CPUID of the platform.

Returns: String formatted to be written to an msr-safe allowlist file.

◆ msr_allowlist() [2/2]

std::string geopm::MSRIOGroup::msr_allowlist	(	int	cpuid,
		const PlatformTopo &	topo,
		std::shared_ptr< MSRIO >	msrio
	)

static

◆ name()

std::string geopm::MSRIOGroup::name ( void ) const

overridevirtual

Get the IOGroup name.

By convention this name is given in all capital letters. This string provides a namespace for the IOGroup since all IOGroups loaded by PlatformIO must have distinct names. This unique namespace may be used in any context to distinguish IOGroups.

One important use case is that the IOGroup name prefixes all low level signal and control names in conjunction with "::". This name prefix may be used to distinguish between the high level signals and controls (i.e. aliases like CPU_FREQUENCY_MAX_CONTROL) that do not contain the IOGroup prefix, and the low level signals and controls that do (e.g. "MSR::PERF_CTL:FREQ").

Returns: The name of the IOGroup in all caps.

Implements geopm::IOGroup.

◆ parse_json_msrs()

void geopm::MSRIOGroup::parse_json_msrs ( const std::string & str )

Parse a JSON string and add any raw MSRs and fields as available signals and controls.

Validate fields within MSR

◆ plugin_name()

std::string geopm::MSRIOGroup::plugin_name ( void )

static

◆ push_control()

int geopm::MSRIOGroup::push_control	(	const std::string &	control_name,
		int	domain_type,
		int	domain_idx
	)

overridevirtual

Add a control to the list of controls that is written by write_batch() and configured with adjust().

Parameters

[in]	control_name	Name of the control requested.
[in]	domain_type	One of the values from the PlatformTopo::m_domain_e enum described in PlatformTopo.hpp.
[in]	domain_idx	The index of the domain within the set of domains of the same type on the platform.

Returns: Index of control when adjust() method is called.

Implements geopm::IOGroup.

◆ push_signal()

int geopm::MSRIOGroup::push_signal	(	const std::string &	signal_name,
		int	domain_type,
		int	domain_idx
	)

overridevirtual

Add a signal to the list of signals that is read by read_batch() and sampled by sample().

Parameters

[in]	signal_name	Name of the signal requested.
[in]	domain_type	One of the values from the PlatformTopo::m_domain_e enum described in PlatformTopo.hpp.
[in]	domain_idx	The index of the domain within the set of domains of the same type on the platform.

Returns: Index of signal when sample() method is called.

Implements geopm::IOGroup.

◆ read_batch()

void geopm::MSRIOGroup::read_batch ( void )

overridevirtual

Read all pushed signals from the platform so that the next call to sample() will reflect the updated data.

Implements geopm::IOGroup.

◆ read_signal()

double geopm::MSRIOGroup::read_signal	(	const std::string &	signal_name,
		int	domain_type,
		int	domain_idx
	)

overridevirtual

Read from platform and interpret into SI units a signal given its name and domain. Does not modify the values stored by calling read_batch().

Parameters

[in]	signal_name	Name of the signal requested.
[in]	domain_type	One of the values from the PlatformTopo::m_domain_e enum described in PlatformTopo.hpp.
[in]	domain_idx	The index of the domain within the set of domains of the same type on the platform.

Returns: The value in SI units of the signal.

Implements geopm::IOGroup.

◆ restore_control() [1/2]

void geopm::MSRIOGroup::restore_control ( const std::string & save_path )

overridevirtual

Implements geopm::IOGroup.

◆ restore_control() [2/2]

void geopm::MSRIOGroup::restore_control ( void )

overridevirtual

Restore all controls to values recorded in previous call to the save() method.

Implements geopm::IOGroup.

◆ sample()

double geopm::MSRIOGroup::sample ( int sample_idx )

overridevirtual

Retrieve signal value from data read by last call to read_batch() for a particular signal previously pushed with push_signal().

Parameters

[in] sample_idx The index returned by previous call to push_signal().

Returns: Value of signal in SI units.

Implements geopm::IOGroup.

◆ save_control() [1/2]

void geopm::MSRIOGroup::save_control ( const std::string & save_path )

overridevirtual

Implements geopm::IOGroup.

◆ save_control() [2/2]

void geopm::MSRIOGroup::save_control ( void )

overridevirtual

Save the state of all controls so that any subsequent changes made through the IOGroup can be undone with a call to the restore() method.

Implements geopm::IOGroup.

◆ signal_behavior()

int geopm::MSRIOGroup::signal_behavior ( const std::string & signal_name ) const

overridevirtual

Returns a hint about how a signal will change as a function of time.

This can be used when generating reports to decide how to summarize a signal's value for the entire application run.

Parameters

[in] signal_name Name of the signal.

Implements geopm::IOGroup.

◆ signal_description()

std::string geopm::MSRIOGroup::signal_description ( const std::string & signal_name ) const

overridevirtual

Returns a description of the signal. This string can be used by tools to generate help text for users of the IOGroup.

Implements geopm::IOGroup.

◆ signal_domain_type()

int geopm::MSRIOGroup::signal_domain_type ( const std::string & signal_name ) const

overridevirtual

Query the domain for a named signal.

Parameters

[in] signal_name Name of the signal to query.

Returns: One of the PlatformTopo::m_domain_e enum values.

Implements geopm::IOGroup.

◆ signal_names()

std::set< std::string > geopm::MSRIOGroup::signal_names ( void ) const

overridevirtual

Returns the names of all signals provided by the IOGroup.

Implements geopm::IOGroup.

◆ write_batch()

void geopm::MSRIOGroup::write_batch ( void )

overridevirtual

Write all of the pushed controls so that values previously given to adjust() are written to the platform.

Implements geopm::IOGroup.

◆ write_control()

void geopm::MSRIOGroup::write_control	(	const std::string &	control_name,
		int	domain_type,
		int	domain_idx,
		double	setting
	)

overridevirtual

Interpret the setting and write setting to the platform. Does not modify the values stored by calling adjust().

Parameters

[in]	control_name	Name of the control requested.
[in]	domain_type	One of the values from the PlatformTopo::m_domain_e enum described in PlatformTopo.hpp.
[in]	domain_idx	The index of the domain within the set of domains of the same type on the platform.
[in]	setting	Value in SI units of the setting for the control.

Implements geopm::IOGroup.

The documentation for this class was generated from the following files:

Public Types

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ m_cpuid_e

Constructor & Destructor Documentation

◆ MSRIOGroup() [1/3]

◆ MSRIOGroup() [2/3]

◆ MSRIOGroup() [3/3]

◆ ~MSRIOGroup()

Member Function Documentation

◆ adjust()

◆ agg_function()

◆ control_description()

◆ control_domain_type()

◆ control_names()

◆ cpuid()

◆ format_function()

◆ is_valid_control()

◆ is_valid_signal()

◆ make_plugin()

◆ make_plugin_safe()

◆ msr_allowlist() [1/2]

◆ msr_allowlist() [2/2]

◆ name()

◆ parse_json_msrs()

◆ plugin_name()

◆ push_control()

◆ push_signal()

◆ read_batch()

◆ read_signal()

◆ restore_control() [1/2]

◆ restore_control() [2/2]

◆ sample()

◆ save_control() [1/2]

◆ save_control() [2/2]

◆ signal_behavior()

◆ signal_description()

◆ signal_domain_type()

◆ signal_names()

◆ write_batch()

◆ write_control()