Skip to content

Latest commit

 

History

History
163 lines (108 loc) · 9.51 KB

WINDOWS_HOWTO.md

File metadata and controls

163 lines (108 loc) · 9.51 KB

COMPILATION AND INSTALLATION OF UTILITIES

For support of systems with more than 64 logical cores you need to compile all binaries below in “x64” platform mode (not the default “Win32” mode).

Command-line utility

  1. Follow Compile the Windows MSR driver to compile the Windows MSR driver (msr.sys). For Windows 7 and later versions you have to sign the msr.sys driver additionally. To enable loading test-signed drivers on the system: in administrator cmd console run bcdedit /set testsigning on and reboot.

  2. Build the pcm.exe utility:

    cmake -B build
cmake --build build --config Release --parallel

    alternatively you can perform cmake -B build, open PCM.sln form build folder in and build required project in Visual Studio. .exe and .dll files will be located in build\bin\Release folder

  3. As Administrator create PCM directory in Windows "Program Files" directory (e.g. C:\Program Files (x86)\PCM\)

  4. As Administrator copy the msr.sys driver and pcm.exe into the PCM directory

  5. Run pcm.exe utility from the PCM directory as Administrator

For Windows 7+ and Windows Server 2008+ R2 the PCM utilities need to be run as Administrator:

Alternatively you can achieve the same using the “Properties” Windows menu of the executable (“Privilege level” setting in the “Compatibility” tab): Right mouse click -> Properties -> Compatibility -> Privilege level -> Set “Run this program as an administrator”.

Screenshot

If you are getting the error Starting MSR service failed with error 3 The system cannot find the path specified. try to uninstall the driver by running pcm --uninstallDriver and optionally reboot the system.

Graphical Perfmon front end

  1. Follow Compile the windows MSR driver to compile the windows MSR driver (msr.sys). For Windows 7 and later versions you have to sign the msr.sys driver additionally (http://msdn.microsoft.com/en-us/library/ms537361(VS.85).aspx).

  2. Copy msr.sys into the c:\windows\system32 directory

  3. Build pcm-lib.dll using Microsoft Visual Studio or cmake

  4. Build 'PCM-Service.exe' using Microsoft Visual Studio or cmake

  5. Copy PCM-Service.exe, PCM-Service.exe.config, and pcm-lib.dll files into the PCM sub-directory in Windows "Program Files" directory (see above)

The config file enables support for legacy security policy. Without this configuration switch, you will get an exception like this:

Unhandled Exception: System.NotSupportedException: This method implicitly uses CAS policy, which has been obsoleted by the .NET Framework.

  1. With administrator rights execute '"PCM-Service.exe" -Install' from this directory

  2. With administrator rights execute 'net start pcmservice'

  3. Start perfmon and find new PCM* counters

If you do not want or cannot compile the msr.sys driver you might use a third-party open source WinRing0 driver instead (experimental only, for testing environments only). Instructions:

  1. Download the free RealTemp utility package from http://www.techpowerup.com/realtemp/ or any other free utility that uses the open-source WinRing0 driver (like OpenHardwareMonitor http://code.google.com/p/open-hardware-monitor/downloads/list).
  2. Copy WinRing0.dll, WinRing0.sys, WinRing0x64.dll, WinRing0x64.sys files from there into the PCM.exe binary location, into the PCM-Service.exe location and into c:\windows\system32
  3. Run the PCM.exe tool and/or go to step 6 (perfmon utility).

Compile the Windows MSR driver

  1. Download Visual Studio (Visual Studio download). When you install Visual Studio, also install related packages:

    • under Workloads, select Desktop development with C++ (select C++ CMake tools for Windows in this workload) and .NET desktop development.
    • under Individual components, search Libs for Spectre and select MSVC v143 - VS 2022 C++ x64/x86 Spectre-mitigated libs(Latest).

  2. Download and install SDK (windows-sdk)

  3. Download and install WDK (windows-wdk). Please select Install Windows Driver Kit Visual Studio extension when you install WDK.

  4. Open a terminal in Visual Studio, then go to src\WinMSRDriver, and run the following command to compile the driver. Then you will see MSR.sys in src\WinMSRDriver\x64\Release.

    MSBuild.exe MSR.vcxproj -property:Configuration=Release -property:Platform=x64

Sign the Windows MSR driver

Run the following in PowerShell, in the directory where MSR.sys is located:

$cert = New-SelfSignedCertificate -Type CodeSigning -Subject "CN=TestCert" -CertStoreLocation "Cert:\CurrentUser\My" -KeyExportPolicy Exportable
$pwd = Read-Host -Prompt "Enter the password for the PFX file" -AsSecureString
Export-PfxCertificate -Cert $cert -FilePath TestCert.pfx -Password $pwd
signtool sign /fd SHA256 /f TestCert.pfx /p ([Runtime.InteropServices.Marshal]::PtrToStringAuto([Runtime.InteropServices.Marshal]::SecureStringToBSTR($pwd))) /t http://timestamp.digicert.com MSR.sys

Afterwards, double-click TestCert.pfx. Install to "Current User" and when able to pick "Place all ...", browse for "Trusted Root Certification Authorities".

Known limitations

Running PCM.exe under Cygwin shell is possible, but due to incompatibilities of signals/events handling between Windows and Cygwin, the PCM may not cleanup PMU configuration after Ctrl+C or Ctrl+Break pressed. The subsequent run of PCM will require to do PMU configuration reset, so adding -r command line option to PCM will be required.

PCM-Service FAQ: Q: Help my service won't start, what can I do to diagnose the problem? A: Please check in the Windows Application "Event Viewer" under "Windows Logs" and then under "Application". PCM-Service writes its messages here, just look for errors. If you can't figure it out how to fix it, create a bug report and make sure to paste the text from the Event Viewer in the bug report so we can diagnose the issue.

Q: I see a message in the Events Viewer that PCM-Service does not start because the "custom counter file view is out of memory", how do I fix this? A: Despite that PCM-Service is reserving more memory than the standard 512kB this error can still occur if there is another application that uses performance counters is initialized before PCM. There are two options:

  1. identify the application or service that starts before PCM-Service and stop or disable it and consequently reboot and try again
  2. find your machine.config file and add `<system.diagnostics>
` to that file

pcm-sensor-server (HTTP/HTTPS server for Grafana integration)

Starting from this release, pcm-sensor-server is now supported on Windows. This utility exposes PCM metrics over HTTP in JSON or Prometheus format for integration with Grafana dashboards.

Building pcm-sensor-server on Windows

  1. Follow the Compile the Windows MSR driver and Sign the Windows MSR driver sections above to compile, sign, and install the MSR driver (msr.sys)

  2. Build pcm-sensor-server:

    cmake -B build
cmake --build build --config Release --target pcm-sensor-server

    The executable will be located in build\bin\Release\pcm-sensor-server.exe

  3. (Optional) For HTTPS support, ensure OpenSSL is installed and available to CMake

Running pcm-sensor-server on Windows

  1. Create a directory for PCM in a protected location (e.g., C:\Program Files\PCM\ or C:\Program Files (x86)\PCM\). Copy msr.sys and pcm-sensor-server.exe to this directory. Important: Do not place PCM binaries in user-writable directories (e.g., Downloads, Desktop, C:\Users\Public\) to prevent DLL planting attacks.

  2. Run as Administrator (required for MSR access):

    pcm-sensor-server.exe

    The server will start on the default port 9738

  3. Common command-line options:

    • -p <port> : Run on a specific port (default is 9738)
    • -D <level> : Set debug verbosity level (0 = no debug, higher = more verbose)
    • -s : Enable HTTPS (requires OpenSSL and certificate files)
    • -h or --help : Show all available options

  4. Access the metrics:

Windows-specific limitations

  • Daemon mode not supported: The -d (daemon/background) option is not available on Windows. The server runs in foreground mode only.
  • Real-time priority not supported: The -R (real-time priority) option is not available on Windows.
  • Signal handling: Use Ctrl+C to gracefully stop the server instead of SIGTERM/SIGINT.

Example: Running with Grafana on Windows

  1. Start pcm-sensor-server as Administrator:

    pcm-sensor-server.exe -p 9738

  2. Configure Prometheus to scrape from http://localhost:9738/metrics

  3. Configure Grafana to use your Prometheus data source

  4. Import the PCM Grafana dashboard (see scripts/grafana/README.md)

For more details on using pcm-sensor-server with Grafana, see PCM-EXPORTER.md.