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, Vcore
• Topology map including Caches for boostrap & 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:
2. GNU C Compiler with GNU extensions
3. GNU Make tool
4. Linux Kernel Header files to build modules
5. Mandatory : CONFIG_MODULES, CONFIG_SMP, CONFIG_X86_MSR
6. 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

7. Forbidden : CONFIG_TRIM_UNUSED_KSYMS

8. 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.
2. See module-signing.rst from the Kernel documentation
3. 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:

2. 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:

2. 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

CoreFreq.  Copyright (C) 2015-2026 CYRIL COURTIAT

Usage:  corefreq-cli [-Option <argument>] [-Command <argument>]

    Interface options
        -Oa     Absolute frequency
        -Op     Show Package C-States
        -Ok     Memory unit in kilobyte
        -Om     Memory unit in megabyte
        -Og     Memory unit in gigabyte
        -OW     Toggle Energy units
        -OF     Temperature in Fahrenheit
        -OJ #   SMBIOS string index number
        -OE #   Color theme index number
        -OY     Show Secret Data

    Command options
        -t <v>  Show Top (default) with optional <v>iew:
                {       frequency, instructions, core, idle, package, tasks,
                        interrupts, sensors, voltage, power, slices, custom }
        -d      Show Dashboard
        -C <#>  Monitor Sensors
        -V <#>  Monitor Voltage
        -W <#>  Monitor Power
        -g <#>  Monitor Package
        -c <#>  Monitor Counters
        -i <#>  Monitor Instructions
        -s      Print System Information
        -j      Print System Information (json-encoded)
        -z      Print Performance Capabilities
        -M      Print Memory Controller
        -R      Print System Registers
        -m      Print Topology
        -u      Print CPUID
        -B      Print SMBIOS
        -k      Print Kernel
        -n      New line
        -h      Print out this message
        -v      Print the version number

Exit status:
        0       SUCCESS         Successful execution
        3       CMD_SYNTAX      Command syntax error
        4       SHM_FILE        Shared memory file error
        5       SHM_MMAP        Shared memory mapping error
        6       PERM_ERR        Execution not permitted
        7       MEM_ERR         Memory operation error
        8       EXEC_ERR        General execution error
        9       SYS_CALL        System call error

Report bugs to labs[at]cyring[.]fr

Daemon

corefreqd -h

Usage:  corefreqd [-option <arguments>]
        -q              Quiet
        -i              Info
        -d              Debug
        -gon            Enable SysGate
        -goff           Disable SysGate
        -U <decimal>    Set the effective user ID
        -G <decimal>    Set the effective group ID
        -M <oct>,<oct>  Shared Memories permission
        -h              Print out this message
        -v              Print the version number

Exit status:
        0       SUCCESS         Successful execution
        3       CMD_SYNTAX      Command syntax error
        4       SHM_FILE        Shared memory file error
        5       SHM_MMAP        Shared memory mapping error
        6       PERM_ERR        Execution not permitted
        7       MEM_ERR         Memory operation error
        8       EXEC_ERR        General execution error
        9       SYS_CALL        System call error

Report bugs to labs[at]cyring[.]fr

Driver

modinfo corefreqk.ko

```console parm: ArchID:Force an architecture (ID) (int) parm: AutoClock:Estimate Clock Frequency 0:Spec; 1:Once; 2:Auto (int) parm: SleepInterval:Timer interval (ms) (uint) parm: TickInterval:System requested interval (ms) (uint) parm: Experimental:Enable features under development (int) parm: CPU_Count:-1:Kernel(default); 0:Hardware; >0: User value (int) parm: Target_Ratio_Unlock:1:Target Ratio Unlock; 0:Lock (short) parm: Clock_Ratio_Unlock:1:MinRatio; 2:MaxRatio; 3:Both Unlock (short) parm: Turbo_Ratio_Unlock:1:Turbo Ratio Unlock; 0:Lock (short) parm: Uncore_Ratio_Unlock:1:Uncore Ratio Unlock; 0:Lock (short) parm: ServiceProcessor:Select a CPU to run services with (int) parm: RDPMC_Enable:Enable RDPMC bit in CR4 register (ushort) parm: NMI_Disable:Disable the NMI Handler (ushort) parm: Override_SubCstate:Override Sub C-States (array of ushort) parm: PkgCStateLimit:Package C-State Limit (short) parm: IOMWAIT_Enable:I/O MWAIT Redirection Enable (short) parm: CStateIORedir:Power Mgmt IO Redirection C-State (short) parm: Config_TDP_Level:Config TDP Control Level (short) parm: Custom_TDP_Offset:TDP Limit Offset (watt) (array of short) parm: Activate_TDP_Limit:Activate TDP Limiting (array of short) parm: Activate_TDP_Clamp:Activate TDP Clamping (array of short) parm: Custom_TDC_Offset:TDC Limit Offset (amp) (short) parm: Activate_TDC_Limit:Activate TDC Limiting (short) parm: L1_HW_PREFETCH_Disable:Disable L1 HW Prefetcher (short) parm: L1_HW_IP_PREFETCH_Disable:Disable L1 HW IP Prefetcher (short) parm: L1_NPP_PREFETCH_Disable:Disable L1 NPP Prefetcher (short) parm: L1_Scrubbing_Enable:Enable L1 Scrubbing (short) parm: L2_HW_PREFETCH_Disable:Disable L2 HW Prefetcher (short) parm: L2_HW_CL_PREFETCH_Disable:Disable L2 HW CL Prefetcher (short) parm: L2_AMP_PREFETCH_Disable:Adaptive Multipath Probability (short) parm: L2_NLP_PREFETCH_Disable:Disable L2 NLP Prefetcher (short) parm: L1_STRIDE_PREFETCH_Disable:Disable L1 Stride Prefetcher (short) parm: L1_REGION_PREFETCH_Disable:Disable L1 Region Prefetcher (short) parm: L1_BURST_PREFETCH_Disable:Disable L1 Burst Prefetcher (short) parm: L2_STREAM_PREFETCH_Disable:Disable L2 Stream Prefetcher (short) parm: L2_UPDOWN_PREFETCH_Disable:Disable L2 Up/Down Prefetcher (short) parm: LLC_Streamer_Disable:Disable LLC Streamer (short) parm: SpeedStep_Enable:Enable SpeedStep (short) parm: C1E_Enable:Enable SpeedStep C1E (short) parm: TurboBoost_Enable:Enable Turbo Boost (array of short) parm: C3A_Enable:Enable C3 Auto Demotion (short) parm: C1A_Enable:Enable C3 Auto Demotion (short) parm: C3U_Enable:Enable C3 UnDemotion (short) parm: C1U_Enable:Enable C1 UnDemotion (short) parm: C2U_Enable:Enable C2 UnDemotion (short) parm: CC6_Enable:Enable Core C6 State (short) parm: PC6_Enable:Enable Package C6 State (short) parm: ODCM_Enable:Enable On-Demand Clock Modulation (short) parm: ODCM_DutyCycle:ODCM DutyCycle [0-7] | [0-14] (short) parm: PowerMGMT_Unlock:Unlock Power Management (short) parm: PowerPolicy:Power Policy Preference [0-15] (short) parm: Turbo_Activation_Ratio:Turbo Activation Ratio (short) parm: PState_FID:P-State Frequency Id (int) parm: PState_VID:P-State Voltage Id (int) parm: Ratio_Boost:Turbo Boost Frequency ratios (array of int) parm: Ratio_PPC:Target Performance ratio (int) parm: HWP_Enable:Hardware-Controlled Performance States (short) parm: HWP_EPP:Energy Performance Preference (short) parm: Ratio_HWP:Hardware-Controlled Performance ratios (array of int) parm: HDC_Enable:Hardware Duty Cycling (short) parm: EEO_Disable:Disable Energy Efficiency Optimization (short) parm: R2H_Disable:Disable Race to Halt (short) parm: Clear_Events:Clear Thermal and Power Events (ullong) parm: ThermalOffset:Thermal Offset (short) parm: ThermalScope:[0:None; 1:SMT; 2:Core; 3:Package] (int) parm: VoltageScope:[0:None; 1:SMT; 2:Core; 3:Package] (int) parm: PowerScope:[0:None; 1:SMT; 2:Core; 3:Package] (int) parm: Register_CPU_Idle:Register the Kernel cpuidle driver (short) parm: Register_CPU_Freq:Register the Kernel cpufreq driver (short) parm: Register_Governor:Register the Kernel governor (short) parm: Register_ClockSource:Register Clock Source driver (short) parm: Idle_Route:[0:Default; 1:I/O; 2:HALT; 3:MWAIT] (short) parm: Mech_IBRS:Mit