msr_core.h File Reference

#include <linux/types.h>
#include <stdint.h>
#include <sys/types.h>

Include dependency graph for msr_core.h:

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

Go to the source code of this file.

Classes
struct	msr_batch_op
	Structure holding information for a single read/write operation to an MSR. More...
struct	msr_batch_array
	Structure holding multiple read/write operations to various MSRs. More...

Macros
#define	NUM_DEVS   (sockets * coresPerSocket * threadsPerCore)
#define	X86_IOC_MSR_BATCH   _IOWR('c', 0xA2, struct msr_batch_array)
#define	MSR_BATCH_DIR   "/dev/cpu/msr_batch"
#define	FILENAME_SIZE   1024

Enumerations
enum	libmsr_data_type_e {   RAPL_DATA,   RAPL_UNIT,   FIXED_COUNTERS_DATA,   FIXED_COUNTERS_CTR_DATA,   COUNTERS_DATA,   COUNTERS_CTRL,   CLOCKS_DATA,   PERF_DATA,   THERM_STAT,   THERM_INTERR,   PKG_THERM_STAT,   PKG_THERM_INTERR,   TEMP_TARGET,   PERF_CTL,   PKG_CRES,   CORE_CRES,   UNCORE_EVTSEL,   UNCORE_COUNT,   USR_BATCH0,   USR_BATCH1,   USR_BATCH2,   USR_BATCH3,   USR_BATCH4,   USR_BATCH5,   USR_BATCH6,   USR_BATCH7,   USR_BATCH8,   USR_BATCH9,   USR_BATCH10 }
	Enum encompassing type of data being read to/written from MSRs. More...
enum	libmsr_batch_op_type_e {   BATCH_LOAD,   BATCH_WRITE,   BATCH_READ }
	Enum encompassing batch operations. More...

Functions
uint64_t	num_cores (void)
	Retrieve the number of cores existing on the platform.
uint64_t	num_sockets (void)
	Retrieve the number of sockets existing on the platform.
uint64_t	num_devs (void)
	Retrieve total number of logical processors existing on the platform.
uint64_t	cores_per_socket (void)
	Retrieve number of cores per socket existing on the platform.
int	allocate_batch (int batchnum, size_t bsize)
	Allocate space for new batch operation.
int	free_batch (int batchnum)
	Deallocate memory for specific set of batch operations.
int	create_batch_op (off_t msr, uint64_t cpu, uint64_t **dest, const int batchnum)
	Create new batch operation.
void	core_config (uint64_t *coresPerSocket, uint64_t *threadsPerCore, uint64_t *sockets, int *HTenabled)
	Detect platform configuration.
int	sockets_assert (const unsigned *socket, const int location, const char *file)
	Validate specific socket exists in the platform configuration.
int	threads_assert (const unsigned *thread, const int location, const char *file)
	Validate specific thread exists in the platform configuration.
int	cores_assert (const unsigned *core, const int location, const char *file)
	Validate specific core exists in the platform configuration.
int	stat_module (char *filename, int *kerneltype, int *dev_idx)
	Check status of a file.
int	init_msr (void)
	Open the MSR module file descriptors exposed in the /dev filesystem.
int	finalize_msr (void)
	Close the MSR module file descriptors exposed in the /dev filesystem.
int	write_msr_by_coord (unsigned socket, unsigned core, unsigned thread, off_t msr, uint64_t val)
	Write a new value to an MSR based on the coordinates of a core or thread.
int	read_msr_by_coord (unsigned socket, unsigned core, unsigned thread, off_t msr, uint64_t *val)
	Read current value of an MSR based on the coordinates of a core or thread.
int	read_msr_by_coord_batch (unsigned socket, unsigned core, unsigned thread, off_t msr, uint64_t **val, int batchnum)
	Perform batch read of multiple MSR based on the coordinates of a core or thread.
int	read_batch (const int batchnum)
	Do batch read operation.
int	write_batch (const int batchnum)
	Do batch write operation.
int	load_socket_batch (off_t msr, uint64_t **val, const int batchnum)
	Load batch operations for a socket.
int	load_core_batch (off_t msr, uint64_t **val, const int batchnum)
	Load batch operations for a core.
int	load_thread_batch (off_t msr, uint64_t **val, const int batchnum)
	Load batch operations for a thread.
int	read_msr_by_idx (int dev_idx, off_t msr, uint64_t *val)
	Read current value of an MSR based on the index of a core or thread.
int	write_msr_by_idx (int dev_idx, off_t msr, uint64_t val)
	Write new value to an MSR based on the index of a core or thread.
int	write_msr_by_idx_and_verify (int dev_idx, off_t msr, uint64_t val)
	Verify successful MSR write by following operation immediately with a read.

Macro Definition Documentation

#define FILENAME_SIZE   1024

#define MSR_BATCH_DIR   "/dev/cpu/msr_batch"

#define NUM_DEVS   (sockets * coresPerSocket * threadsPerCore)

#define X86_IOC_MSR_BATCH   _IOWR('c', 0xA2, struct msr_batch_array)

Enumeration Type Documentation

enum libmsr_batch_op_type_e

Enum encompassing batch operations.

Enumerator:

BATCH_LOAD	Load batch operation.
BATCH_WRITE	Write batch operation.
BATCH_READ	Read batch operation.

enum libmsr_data_type_e

Enum encompassing type of data being read to/written from MSRs.

Enumerator:

RAPL_DATA	Energy, time, and power measurements of various RAPL power domains.
RAPL_UNIT	Units for energy, time, and power across all RAPL power domains.
FIXED_COUNTERS_DATA	Fixed-function counter measurements (i.e., instructions retired, reference clock cycles, CPU cycles).
FIXED_COUNTERS_CTR_DATA	Controls for fixed-function counters (i.e., instructions retired, reference clock cycles, CPU cycles).
COUNTERS_DATA	General-purpose performance counter measurements.
COUNTERS_CTRL	Controls for general-purpose performance counters and performance event select counter measurements.
CLOCKS_DATA	Clock cycle measurements based on fixed frequency and actual frequency of the processor.
PERF_DATA	Instantaneous operating frequency of the core or socket.
THERM_STAT	Thermal status of core.
THERM_INTERR	Interrupts by thermal monitor when thermal sensor on a core is tripped.
PKG_THERM_STAT	Thermal status of package.
PKG_THERM_INTERR	Interrupts by thermal monitor when thermal sensor on the package is tripped.
TEMP_TARGET	Current temperature of the package.
PERF_CTL	Software desired operating frequency of the core or socket.
PKG_CRES	Measured time spent in C-states by the package.
CORE_CRES	Measured time spent in C-states by the core.
UNCORE_EVTSEL	Uncore performance event select counter measurements.
UNCORE_COUNT	Uncore general-performance counter measurements.
USR_BATCH0	User-defined batch MSR data.
USR_BATCH1	User-defined batch MSR data.
USR_BATCH2	User-defined batch MSR data.
USR_BATCH3	User-defined batch MSR data.
USR_BATCH4	User-defined batch MSR data.
USR_BATCH5	User-defined batch MSR data.
USR_BATCH6	User-defined batch MSR data.
USR_BATCH7	User-defined batch MSR data.
USR_BATCH8	User-defined batch MSR data.
USR_BATCH9	User-defined batch MSR data.
USR_BATCH10	User-defined batch MSR data.

Function Documentation

int allocate_batch	(	int	batchnum,
		size_t	bsize
	)

Allocate space for new batch operation.

Parameters

[in]	batchnum	libmsr_data_type_e data type of batch operation.
[in]	bsize	Size of batch operation.

Returns

0 if allocation was a success, else -1 if batch_storage() fails.

void core_config	(	uint64_t *	coresPerSocket,
		uint64_t *	threadsPerCore,
		uint64_t *	sockets,
		int *	HTenabled
	)

Detect platform configuration.

Parameters

[out]	coresPerSocket	Number of cores per socket.
[out]	threadsPerCore	Number of threads per core.
[out]	sockets	Number of sockets.
[out]	HTenabled	Indicates if hyperthreading is enabled/disabled.

int cores_assert	(	const unsigned *	core,
		const int	location,
		const char *	file
	)

Validate specific core exists in the platform configuration.

Parameters

[in]	core	Unique core identifier.
[in]	location	Line number in source file where error occurred (use standard predefined macro LINE).
[in]	file	Name of source file where error occurred (use standard predefined macro FILE).

Returns

0 if successful, else -1 if core requested is greater than number of cores per socket in the platform.

uint64_t cores_per_socket

(

void

)

Retrieve number of cores per socket existing on the platform.

Returns

Number of cores per socket.

int create_batch_op	(	off_t	msr,
		uint64_t	cpu,
		uint64_t **	dest,
		const int	batchnum
	)

Create new batch operation.

Parameters

[in]	msr	Address of MSR for which operation will take place.
[in]	cpu	CPU where batch operation will take place.
[in]	dest	Stores data resulting from rdmsr or necessary for wrmsr.
[in]	batchnum	libmsr_data_type_e data type of batch operation.

Returns

0 if creation was a success, else -1 if batch_storage() fails or if the number of batch operations exceeds the allocated size.

int finalize_msr

(

void

)

Close the MSR module file descriptors exposed in the /dev filesystem.

Returns

0 if finalization was a success, else -1 if could not close file descriptors.

int free_batch

(

int

batchnum

)

Deallocate memory for specific set of batch operations.

Parameters

[in]

batchnum

libmsr_data_type_e data type of batch operation.

Returns

0 if successful, else -1 if batch_storage() fails.

int init_msr

(

void

)

Open the MSR module file descriptors exposed in the /dev filesystem.

Returns

0 if initialization was a success, else -1 if could not stat file descriptors or open any msr module.

int load_core_batch	(	off_t	msr,
		uint64_t **	val,
		const int	batchnum
	)

Load batch operations for a core.

Parameters

[in]	msr	Address of register to load.
[in]	val	Pointer to batch storage array.
[in]	batchnum	libmsr_data_type_e data type of batch operation.

Returns

0 if successful, else -1 if batch storage array is uninitialized.

Todo:

dev_idx++?

int load_socket_batch	(	off_t	msr,
		uint64_t **	val,
		const int	batchnum
	)

Load batch operations for a socket.

Parameters

[in]	msr	Address of register to load.
[in]	val	Pointer to batch storage array.
[in]	batchnum	libmsr_data_type_e data type of batch operation.

Returns

0 if successful, else -1 if batch storage array is uninitialized.

int load_thread_batch	(	off_t	msr,
		uint64_t **	val,
		const int	batchnum
	)

Load batch operations for a thread.

Parameters

[in]	msr	Address of register to load.
[in]	val	Pointer to batch storage array.
[in]	batchnum	libmsr_data_type_e data type of batch operation.

Returns

0 if successful, else -1 if batch storage array is uninitialized.

uint64_t num_cores

(

void

)

Retrieve the number of cores existing on the platform.

Returns

Number of cores.

uint64_t num_devs

(

void

)

Retrieve total number of logical processors existing on the platform.

Returns

Total number of logical processors.

uint64_t num_sockets

(

void

)

Retrieve the number of sockets existing on the platform.

Returns

Number of sockets.

int read_batch

(

const int

batchnum

)

Do batch read operation.

Parameters

[in]

batchnum

libmsr_data_type_e data type of batch operation.

int read_msr_by_coord	(	unsigned	socket,
		unsigned	core,
		unsigned	thread,
		off_t	msr,
		uint64_t *	val
	)

Read current value of an MSR based on the coordinates of a core or thread.

A user can request to read from core 4 on socket 1, instead of having to map this core to a continuous value based on the the number of cores on socket 0. For a dual socket system with 8 cores, socket 0 would have cores 0-7, core 0 on socket 1 would be mapped to index 8.

Parameters

[in]	socket	Unique socket/package identifier.
[in]	core	Unique core identifier.
[in]	thread	Unique thread identifier.
[in]	msr	Address of register to read.
[out]	val	Value read from MSR.

Returns

0 if read_msr_by_idx() was a success, else -1 if the file descriptor was NULL or if the number of bytes read was not the size of uint64_t.

int read_msr_by_coord_batch	(	unsigned	socket,
		unsigned	core,
		unsigned	thread,
		off_t	msr,
		uint64_t **	val,
		int	batchnum
	)

Perform batch read of multiple MSR based on the coordinates of a core or thread.

Parameters

[in]	socket	Unique socket/package identifier.
[in]	core	Unique core identifier.
[in]	thread	Unique thread identifier.
[in]	msr	Address of register to read.
[out]	val	Value read from MSR.
[in]	batchnum	libmsr_data_type_e data type of batch operation.

Returns

0 if read_msr_by_idx() was a success, else -1 if the file descriptor was NULL or if the number of bytes read was not the size of uint64_t.

int read_msr_by_idx	(	int	dev_idx,
		off_t	msr,
		uint64_t *	val
	)

Read current value of an MSR based on the index of a core or thread.

A user can request to read from index 8, which is core 0 on socket 1 in a dual socket system with 8 cores per socket. This index is a continuous value based on the the number of cores on socket 0.

Parameters

[in]	dev_idx	Unique device identifier.
[in]	msr	Address of register to read.
[out]	val	Value read from MSR.

Returns

0 if successful, else -1 if file descriptor was NULL or if the number of bytes read was not the size of uint64_t.

int sockets_assert	(	const unsigned *	socket,
		const int	location,
		const char *	file
	)

Validate specific socket exists in the platform configuration.

Parameters

[in]	socket	Unique socket/package identifier.
[in]	location	Line number in source file where error occurred (use standard predefined macro LINE).
[in]	file	Name of source file where error occurred (use standard predefined macro FILE).

Returns

0 if successful, else -1 if socket requested is greater than number of sockets in the platform.

int stat_module	(	char *	filename,
		int *	kerneltype,
		int *	dev_idx
	)

Check status of a file.

Parameters

[in]	filename	File to check status of.
[in]	kerneltype	OS privilege level (ring 0-ring 3).
[in]	dev_idx	Unique logical processor index.

Returns

0 if successful, else -1 if can't find any msr module with RW permissions.

int threads_assert	(	const unsigned *	thread,
		const int	location,
		const char *	file
	)

Validate specific thread exists in the platform configuration.

Parameters

[in]	thread	Unique thread identifier.
[in]	location	Line number in source file where error occurred (use standard predefined macro LINE).
[in]	file	Name of source file where error occurred (use standard predefined macro FILE).

Returns

0 if successful, else -1 if thread requested is greater than number of threads per core in the platform.

int write_batch

(

const int

batchnum

)

Do batch write operation.

Parameters

[in]

batchnum

libmsr_data_type_e data type of batch operation.

int write_msr_by_coord	(	unsigned	socket,
		unsigned	core,
		unsigned	thread,
		off_t	msr,
		uint64_t	val
	)

Write a new value to an MSR based on the coordinates of a core or thread.

A user can request to write to core 4 on socket 1, instead of having to map this core to a continuous value based on the the number of cores on socket 0. For a dual socket system with 8 cores, socket 0 would have cores 0-7, core 0 on socket 1 would be mapped to index 8.

Parameters

[in]	socket	Unique socket/package identifier.
[in]	core	Unique core identifier.
[in]	thread	Unique thread identifier.
[in]	msr	Address of register to write.
[in]	val	Value to write to MSR.

Returns

0 if write_msr_by_idx() was a success, else -1 if the file descriptor was NULL or if the number of bytes written was not the size of uint64_t.

int write_msr_by_idx	(	int	dev_idx,
		off_t	msr,
		uint64_t	val
	)

Write new value to an MSR based on the index of a core or thread.

A user can request to read from index 8, which is core 0 on socket 1 in a dual socket system with 8 cores per socket. This index is a continuous value based on the the number of cores on socket 0.

Parameters

[in]	dev_idx	Unique device identifier.
[in]	msr	Address of register to read.
[out]	val	Value read from MSR.

Returns

0 if successful, else -1 if file descriptor was NULL or if the number of bytes read was not the size of uint64_t.

int write_msr_by_idx_and_verify	(	int	dev_idx,
		off_t	msr,
		uint64_t	val
	)

Verify successful MSR write by following operation immediately with a read.

Parameters

[in]	dev_idx	Unique device identifier.
[in]	msr	Address of register to read.
[out]	val	Value read from MSR.

Returns

0 if successful, else -1 if file descriptor was NULL, if the number of bytes written was not the size of uint64_t, if the read function failed, or if the value written does not match the read value.