CoreFreq

CoreFreq

Purpose

CoreFreq, CPU monitoring software with BIOS like functionalities, is designed for the 64-bit Processors of architecture Intel Atom, Core2, Nehalem, SandyBridge and superiors; AMD Families from 0Fh ... up to 17h (Zen , Zen+ , Zen 2), 18h (Hygon Dhyana), 19h (Zen 3, Zen 3+, Zen 4, Zen 4c), 1Ah (Zen 5, Zen 5c); Arm A64; RISC-V RV64; PowerPC64 (LE)

CoreFreq provides a framework to retrieve CPU data with a high degree of precision:

• Core frequencies & ratios; SpeedStep (EIST), Turbo Boost, Hyper-Threading (HTT) and Base Clock
• Performance counters including Time Stamp Counter (TSC), Unhalted Core Cycles (UCC), Unhalted Reference Cycles (URC)
• Number of instructions per cycle or second, IPS, IPC, or CPI
• CPU C-States C0 C1 C3 C6 C7 - C1E - Auto/UnDemotion of C1 C3
• DTS Temperature and Tjunction Max, Thermal Monitoring TM1 TM2 state
• Core Voltage (Vcore) iff registers are documented
• Topology map including Caches for bootstrap & application CPU
• Processor features, brand & architecture strings
• In progress: Uncore, Memory Controller channels & geometry, DIMM timings,
  Stress tools, Power & Energy (RAPL, P-State, HWP, TDP), Overclocking, cpuidle & cpufreq driver, ClockSource, Mitigation Mechanisms

To reach this goal, CoreFreq implements a Linux Kernel module which employs the followings:

• asm code to keep as near as possible the readings of the performance counters;
• per-CPU, implements slab data memory and high-resolution timer;
• compliant with suspend / resume and CPU Hot-Plug;
• a shared memory to protect kernel from the user-space part of the software;
• atomic synchronization of threads to avoid mutexes and deadlock.

Build & Run

Prerequisites

a- Intel only: For a better accuracy, disable the Kernel NMI Watchdog

Add the below parameter in the kernel boot loader { Grub, SysLinux } ...

nmi_watchdog=0

... and build with the fixed performance counters

make MSR_CORE_PERF_UC=MSR_CORE_PERF_FIXED_CTR1 MSR_CORE_PERF_URC=MSR_CORE_PERF_FIXED_CTR2

b- AMD and Intel: Some Virtualization

VMs don't provide access to the registers that the CoreFreq driver employs :

• Fixed Performance Counters
• Model Specific Registers
• PCI Registers

However CoreFreq is making use of the virtualized performance counter :

• HV_X64_MSR_VP_RUNTIME(0x40000010)

c- Rendering

The UI renders best with an ASCII console or a Xterm with VT100 support, ANSI colors; optionally transparency.
If bold and bright colors are not rendered then use the following terminal options:

Ubuntu Terminal

In the Preferences - Colors tab, select Show bold text in bright colors

alacritty terminal

Uncomment and set draw_bold_text_with_bright_colors: true in <config-file>

SSH

Force pseudo-terminal allocation. This option is used to execute a menu based application on a remote machine.

ssh -t corefreq-cli

Dependencies

• The Linux Kernel with a minimum version 3.3
• The GNU C Library

Build

1. Software needed:

• GNU C Compiler with GNU extensions
• GNU Make tool
• Linux Kernel Header files to build modules
  • Mandatory : CONFIG_MODULES, CONFIG_SMP, CONFIG_X86_MSR
  • Optionally: CONFIG_HOTPLUG_CPU, CONFIG_CPU_IDLE, CONFIG_CPU_FREQ, CONFIG_PM_SLEEP, CONFIG_DMI, CONFIG_HAVE_NMI, CONFIG_XEN, CONFIG_AMD_NB, CONFIG_SCHED_MUQSS, CONFIG_SCHED_BMQ, CONFIG_SCHED_PDS, CONFIG_SCHED_ALT, CONFIG_SCHED_BORE, CONFIG_CACHY, CONFIG_ACPI, CONFIG_ACPI_CPPC_LIB
  • Forbidden : CONFIG_TRIM_UNUSED_KSYMS

1. Clone the source code into a working directory.

git clone https://github.com/cyring/CoreFreq.git

1. Build the programs.

cd CoreFreq
make -j

  MD [build]
  MD [build/module]
  LN [build/Makefile]
  LN [build/module/corefreqk.c]
  CC [build/corefreqd.o]
  CC [build/corefreqm.o]
  LD [build/corefreqd]
  CC [build/corefreq-cli.o]
  CC [build/corefreq-ui.o]
  CC [build/corefreq-cli-rsc.o]
  CC [build/corefreq-cli-json.o]
  CC [build/corefreq-cli-extra.o]
  LD [build/corefreq-cli]
  CC [M]  module/corefreqk.o
  LD [M]  corefreqk.o
  MODPOST Module.symvers
  CC [M]  corefreqk.mod.o
  CC [M]  .module-common.o
  LD [M]  corefreqk.ko
  BTF [M] corefreqk.ko

1. (Optionally) Sign the driver If module signature verification is enabled into Kernel, you will have to sign the corefreqk.ko driver.

• See module-signing.rst from the Kernel documentation
• See the Gentoo Wiki

Install

Manual

1. Copying CoreFreq into the binaries directory

make install

Distribution package

1. Although CoreFreq is released in the ArchLinux AUR ; other sources of distribution may require to reload the systemd daemons:

systemctl daemon-reload

Start

1. When built from source code:

• Load the kernel module, from current directory, as root.

insmod build/corefreqk.ko

• Start the daemon, as root.

./build/corefreqd

• Start the client, as a user (in another terminal or console).

./build/corefreq-cli

1. When manually installed or from a distribution package:

• Load the kernel module, as root.

modprobe corefreqk

• Start the daemon, as root.

systemctl start corefreqd

• Start the client, as a user.

corefreq-cli

Stop

1. Press Ctrl+x or Ctrl+c to stop the client.

2. Press Ctrl+c to stop the daemon (in foreground) or kill its background job.

3. Unload the kernel module

rmmod corefreqk.ko

Command Line Usage

Client

corefreq-cli -h

…

Daemon

corefreqd -h

…

Driver

modinfo corefreqk.ko

…

Try

Download the CoreFreq Live CD from the Wiki

Screenshots

Linux kernel module

Use lsmod, dmesg or journalctl -k to check if the module is started:

CoreFreq(14:30:-1): Processor [ 8F_71] Architecture [Zen2/Matisse] SMT [32/32]

Daemon

CoreFreq Daemon #.##.#  Copyright (C) 2015-2026 CYRIL COURTIAT

  Processor [AMD Ryzen 9 3950X 16-Core Processor]
  Architecture [Zen2/Matisse] 32/32 CPU Online.

Client

Without arguments, the corefreq-cli program displays Top Monitoring

Remark: Drawing will stall if the terminal width is lower than 80 columns, or its height is less than required.

• Memory Controller

• With the option -c, the client traces counters

• Using option -m corefreq-cli shows the CPU topology

• With the option -i corefreq-cli traces the number of instructions per second / cycle

CPU     IPS            IPC            CPI
#00     0.000579/s     0.059728/c    16.742698/i
#01     0.000334/s     0.150569/c     6.641471/i
#02     0.000598/s     0.161326/c     6.198641/i
#03     0.000294/s     0.233535/c     4.282013/i
#04     0.000240/s     0.042931/c    23.293141/i
#05     0.000284/s     0.158661/c     6.302765/i
#06     0.000128/s     0.128031/c     7.810631/i
#07     0.000088/s     0.150406/c     6.648674/i

• Use the option -s to show the Processor information (BSP)

ArchLinux

• follows released tags

Gentoo Linux

• In GURU overlay CoreFreq package, please contact vitaly-zdanevich

Debian, Ubuntu, TUXEDO

• Installing the DKMS package will pull the Kernel development packages

apt install dkms

• Or install the kernel development prerequisites.

apt list git build-essential gawk fakeroot linux-headers*

Red Hat, CentOS

• Development packages prerequisites.

yum install kernel-devel
yum group install "Development Tools"

Fedora

• In Fedora Copr repository, please contact Sunny Yang

AlmaLinux, Rocky Linux

## as root, install kernel development package and dependencies
dnf --assumeyes install kernel-devel gcc make git bc

## as a User, build CoreFreq
cd CoreFreq
make -j

## as root, install the binaries
make install
## and start Driver and Daemon
modprobe corefreqk
corefreqd

## as a User, start the Client
corefreq-cli

## Terminate Client, Daemon and unload Driver as root
modprobe -r corefreqk
## Proceed to uninstallation as root
cd CoreFreq
make uninstall

openSUSE

• Packages

1. CoreFreq official release
2. CoreFreq-kmp-default

ProxMox

Install Tools

apt-get install build-essential dkms git libpthread-stubs0-dev

Install headers related to your kernel

apt install pve-headers-`uname -r`

git clone https://github.com/cyring/CoreFreq.git
cd CoreFreq && make

Install the module in the system, refresh it and start it

make install
depmod
modprobe corefreqk
systemctl start corefreqd

Unraid

• Plugin

1. corefreq.plg from ich777/unraid-corefreq
2. Based on latest developments, please contact ich777

Alpine

## Install the kernel development packages
apk add alpine-sdk sed installkernel bc nawk diffutils findutils pahole openssl-dev python3 linux-virt linux-virt-dev

Chimera

## Install the kernel development packages
doas apk add git ckms gmake clang linux-headers linux-lts-devel
## Add the CoreFreq directory containing the ckms.ini file
doas ckms add CoreFreq/
## Build the CoreFreq version M.m.r
doas ckms build corefreqk=M.m.r
## Or manually if using the Clang compiler
gmake CC=clang

Clear Linux

Buildroot

Q&A

Q: How many CPUs are supported by CoreFreq ?

A: Up to 1024 CPUs can be built using the make CORE_COUNT option.

256 as a default.

Q: Turbo Technology is activated however CPUs don't reach those frequencies ?

Q: The CPU ratio does not go above its minimum value ?

Q: The UI shows erratic counters values !

A: In the kernel boot command argument line, disable the NMI Watchdog

nmi_watchdog=0

Q: The Processor does not enter the C-States ?

A1: Check if at least one idle driver is running.
According to the processor specs, specify a max_cstate value in the kernel arguments as follow.

intel_idle.max_cstate=<value>

A2: CoreFreq can also register itself as a cpuidle driver.
This time, any idle driver will have to be blacklisted in the kernel command line; such as:

modprobe.blacklist=intel_cstate idle=halt intel_idle.max_cstate=0

Start the CoreFreq driver with the Register_CPU_Idle parameter:

insmod corefreqk.ko Register_CPU_Idle=1

Q: The CoreFreq UI refreshes itself slowly, with a delay after the actual CPUs usage ?

A: The sampling time to read the counters can be reduced or increased using a CoreFreq module argument:

insmod corefreqk.ko SleepInterval=<value>

where <value> is supplied in milliseconds between a minimum of 100 ms and a maximum of 4500 ms.

1000 ms is the default value.

Q: The base clock reports a wrong frequency value ?

A: _CoreF