### Install CoreCtrl on Fedora

Source: https://gitlab.com/corectrl/corectrl/-/blob/master/README.md

Use dnf to install CoreCtrl on Fedora systems.

```bash
sudo dnf install corectrl
```

--------------------------------

### Install CoreCtrl on Debian/Ubuntu

Source: https://gitlab.com/corectrl/corectrl/-/blob/master/README.md

Use apt to install CoreCtrl on Debian and Ubuntu systems.

```bash
sudo apt install corectrl
```

--------------------------------

### Install CoreCtrl on Gentoo

Source: https://gitlab.com/corectrl/corectrl/-/blob/master/README.md

Add the farmboy0 overlay and then use emerge to install CoreCtrl on Gentoo systems.

```bash
emerge --ask --verbose kde-misc/corectrl
```

--------------------------------

### Build CoreCtrl from Source

Source: https://context7.com/corectrl/corectrl/llms.txt

Commands to install dependencies, configure the build with CMake, and compile the project.

```bash
# Install dependencies (Arch Linux)
sudo pacman -S cmake qt6-base qt6-declarative qt6-charts qt6-svg \
    qt6-tools botan spdlog pugixml quazip-qt6

# Install dependencies (Ubuntu/Debian)
sudo apt install cmake qt6-base-dev qt6-declarative-dev qt6-charts-dev \
    qt6-svg-dev qt6-tools-dev libbotan-2-dev libspdlog-dev libpugixml-dev \
    libquazip1-qt6-dev

# Clone and build
git clone https://gitlab.com/corectrl/corectrl.git
cd corectrl
mkdir build && cd build

# Configure (Release build)
cmake -DCMAKE_BUILD_TYPE=Release ..

# Configure with custom options
cmake -DCMAKE_BUILD_TYPE=Release \
      -DWITH_PCI_IDS_PATH="/usr/share/hwdata/pci.ids" \
      -DBUILD_TESTING=ON \
      ..

# Build
make -j$(nproc)

# Install
sudo make install

# Uninstall
sudo make uninstall
```

--------------------------------

### Configure Dependencies and Paths

Source: https://gitlab.com/corectrl/corectrl/-/blob/master/src/helper/CMakeLists.txt

Locates required libraries and determines installation directories for D-Bus and Polkit using pkg-config.

```cmake
find_package(PkgConfig REQUIRED)

find_package(Botan QUIET)
if(NOT Botan_FOUND)
  message(FATAL_ERROR "Botan library not found")
endif()


set(DBUS_DATADIR_PREFIX_DIR ${CMAKE_INSTALL_FULL_DATADIR})
option(INSTALL_DBUS_FILES_IN_PREFIX "Use installation prefix for D-Bus files" OFF)

# Find dbus
if(NOT INSTALL_DBUS_FILES_IN_PREFIX)
  pkg_check_modules(DBUS REQUIRED dbus-1)
  execute_process(
    COMMAND pkg-config --variable=datadir dbus-1
    RESULT_VARIABLE DBUS_DATADIR_PREFIX_DIR_RESULT
    OUTPUT_VARIABLE DBUS_DATADIR_PREFIX_DIR
    OUTPUT_STRIP_TRAILING_WHITESPACE
  )
  if(NOT DBUS_DATADIR_PREFIX_DIR_RESULT EQUAL "0")
    message(FATAL_ERROR "Failed to retrieve D-Bus `datadir` variable using pkg-config")
  endif()
endif()
message("D-Bus files will be installed into ${DBUS_DATADIR_PREFIX_DIR}/dbus-1")

# Find polkit
pkg_check_modules(POLKIT REQUIRED polkit-gobject-1)

option(POLKIT_POLICY_INSTALL_DIR "Polkit policy files installation directory" OFF)
if(NOT POLKIT_POLICY_INSTALL_DIR)
  execute_process(
    COMMAND pkg-config --variable=policydir polkit-gobject-1
    RESULT_VARIABLE POLKIT_POLICY_INSTALL_DIR_RESULT
    OUTPUT_VARIABLE POLKIT_POLICY_INSTALL_DIR
    OUTPUT_STRIP_TRAILING_WHITESPACE
  )
  if(NOT POLKIT_POLICY_INSTALL_DIR_RESULT EQUAL "0")
    message(FATAL_ERROR "Failed to retrieve Polkit `policydir` variable using pkg-config")
  endif()
endif()
message("Polkit policy files will be installed into ${POLKIT_POLICY_INSTALL_DIR}")
```

--------------------------------

### Install CoreCtrl on Arch Linux

Source: https://gitlab.com/corectrl/corectrl/-/blob/master/README.md

Use pacman to install CoreCtrl on Arch Linux systems.

```bash
pacman -S corectrl
```

--------------------------------

### Build corectrl_helper Executable

Source: https://gitlab.com/corectrl/corectrl/-/blob/master/src/helper/CMakeLists.txt

Configures the main helper executable, including its dependencies and installation rules.

```cmake
set(CMAKE_AUTOMOC ON)
add_executable(corectrl_helper
  helper.cpp
  polkit.cpp
  ${COMMON_SRC}
  ${CRYPTO_SRC}
  ${PROCESS_MONITOR_SRC}
  ${SYSTEM_CONTROL_SRC}
)
set(CMAKE_AUTOMOC OFF)

target_include_directories(corectrl_helper PRIVATE
  ${Botan_INCLUDE_DIRS}
  ${POLKIT_INCLUDE_DIRS}
  ${PROJECT_SOURCE_DIR}/src
)
target_compile_definitions(corectrl_helper PRIVATE ${HELPER_COMPILE_DEFINITIONS})
target_link_libraries(corectrl_helper PRIVATE
  Qt6::Core
  Qt6::DBus
  stdc++fs
  pthread
  spdlog::spdlog
  ${Botan_LIBRARIES}
  ${POLKIT_LIBRARIES}
  ${ATOMIC_LIB}
)

configure_file(org.corectrl.helper.service.in org.corectrl.helper.service)
install(TARGETS corectrl_helper DESTINATION "${CMAKE_INSTALL_FULL_LIBEXECDIR}/corectrl")
install(FILES org.corectrl.helper.conf DESTINATION "${DBUS_DATADIR_PREFIX_DIR}/dbus-1/system.d")
install(FILES "${CMAKE_CURRENT_BINARY_DIR}/org.corectrl.helper.service" DESTINATION "${DBUS_DATADIR_PREFIX_DIR}/dbus-1/system-services")
install(FILES org.corectrl.helper.policy DESTINATION "${POLKIT_POLICY_INSTALL_DIR}")
```

--------------------------------

### Build corectrl_helperkiller Executable

Source: https://gitlab.com/corectrl/corectrl/-/blob/master/src/helper/CMakeLists.txt

Configures the helperkiller executable, including its dependencies and installation rules.

```cmake
set(CMAKE_AUTOMOC ON)
add_executable(corectrl_helperkiller
  helperkiller.cpp
  polkit.cpp
)
set(CMAKE_AUTOMOC OFF)

target_include_directories(corectrl_helperkiller PRIVATE
  ${POLKIT_INCLUDE_DIRS}
)
target_compile_definitions(corectrl_helperkiller PRIVATE ${HELPER_COMPILE_DEFINITIONS})
target_link_libraries(corectrl_helperkiller PRIVATE
  Qt6::Core
  Qt6::DBus
  spdlog::spdlog
  ${POLKIT_LIBRARIES}
  ${ATOMIC_LIB}
)

configure_file(org.corectrl.helperkiller.service.in org.corectrl.helperkiller.service)
install(TARGETS corectrl_helperkiller DESTINATION "${CMAKE_INSTALL_FULL_LIBEXECDIR}/corectrl")
install(FILES org.corectrl.helperkiller.conf DESTINATION "${DBUS_DATADIR_PREFIX_DIR}/dbus-1/system.d")
install(FILES "${CMAKE_CURRENT_BINARY_DIR}/org.corectrl.helperkiller.service" DESTINATION "${DBUS_DATADIR_PREFIX_DIR}/dbus-1/system-services")
install(FILES org.corectrl.helperkiller.policy DESTINATION "${POLKIT_POLICY_INSTALL_DIR}")
```

--------------------------------

### AMD Power Management Configuration Example

Source: https://context7.com/corectrl/corectrl/llms.txt

Illustrates the XML structure for configuring AMD power management settings and the corresponding sysfs commands generated by CoreCtrl. Values are specified in Watts and MHz, then converted to microwatts and MHz for sysfs.

```xml
<AMD_PM_ADVANCED active="true">
  <AMD_PM_POWERCAP active="true">
    <value>200</value>  <!-- Watts -->
  </AMD_PM_POWERCAP>
  <AMD_PM_POWER_PROFILE active="true">
    <mode>3D_FULL_SCREEN</mode>
  </AMD_PM_POWER_PROFILE>
  <AMD_PM_OVERDRIVE active="true">
    <AMD_PM_FREQ_RANGE active="true" controlName="SCLK">
      <min>800</min>   <!-- MHz -->
      <max>2100</max>
    </AMD_PM_FREQ_RANGE>
  </AMD_PM_OVERDRIVE>
</AMD_PM_ADVANCED>
```

```bash
echo "manual" > /sys/class/drm/card0/device/power_dpm_force_performance_level
echo "200000000" > /sys/class/drm/card0/device/hwmon/hwmon*/power1_cap
echo "1" > /sys/class/drm/card0/device/pp_power_profile_mode
echo "s 0 800" > /sys/class/drm/card0/device/pp_od_clk_voltage
echo "s 1 2100" > /sys/class/drm/card0/device/pp_od_clk_voltage
echo "c" > /sys/class/drm/card0/device/pp_od_clk_voltage
```

--------------------------------

### Configure APT preferences for CoreCtrl PPA

Source: https://gitlab.com/corectrl/corectrl/-/blob/master/README.md

Create a preferences file to manage CoreCtrl installation from the Ernst ppa-mesarc repository on Debian/Ubuntu. This configuration prevents other packages from the PPA from being preferred, ensuring only CoreCtrl is upgraded from this source.

```bash
# Never prefer packages from the ernstp repository
Package: *
Pin: release o=LP-PPA-ernstp-mesarc
Pin-Priority: 1

# Allow upgrading only corectrl from LP-PPA-ernstp-mesarc
Package: corectrl
Pin: release o=LP-PPA-ernstp-mesarc
Pin-Priority: 500
```

--------------------------------

### Fan Curve Usage Example

Source: https://context7.com/corectrl/corectrl/llms.txt

Example of how to define a custom fan curve with temperature and speed points, and a representation for XML serialization.

```cpp
// Usage example: Fan curve configuration
// Define a custom fan curve (temperature in Celsius -> speed percentage)
std::vector<AMD::FanCurve::Point> customCurve = {
    {units::temperature::celsius_t(30), units::concentration::percent_t(20)},
    {units::temperature::celsius_t(50), units::concentration::percent_t(40)},
    {units::temperature::celsius_t(70), units::concentration::percent_t(70)},
    {units::temperature::celsius_t(85), units::concentration::percent_t(100)}
};

// Fan curve profile part example for XML serialization
// Stored in profile XML:
// <AMD_FAN_CURVE active="true">
//   <fanStop>true</fanStop>
//   <fanStartValue>30</fanStartValue>
//   <curve>
//     <point temp="30" speed="20"/>
//     <point temp="50" speed="40"/>
//     <point temp="70" speed="70"/>
//     <point temp="85" speed="100"/>
//   </curve>
// </AMD_FAN_CURVE>

```

--------------------------------

### Uninstall CoreCtrl Files

Source: https://gitlab.com/corectrl/corectrl/-/blob/master/CHANGELOG.md

Use these commands to remove old CoreCtrl files if you installed from source and are upgrading to a version that changes file locations or removes dependencies.

```bash
sudo rm /usr/share/applications/CoreCtrl.desktop /usr/share/icons/hicolor/196x196/apps/corectrl.svg
```

```bash
sudo rm /usr/share/applications/CoreCtrl.desktop
sudo rm -rf /usr/share/icons/hicolor/196x196
```

--------------------------------

### Manage Application Settings

Source: https://context7.com/corectrl/corectrl/llms.txt

Provides a wrapper around QSettings for persistent storage of application preferences. Includes support for signals to notify when settings change.

```cpp
#include "app/settings.h"

class Settings : public QSettings {
    Q_OBJECT

public:
    Settings(QString const &appName) noexcept;

    // Store and retrieve simple values
    Q_INVOKABLE void setValue(QString const &key, QVariant const &value);
    Q_INVOKABLE QVariant getValue(QString const &key,
                                  QVariant const &defaultValue) const;

    // Store and retrieve string lists
    Q_INVOKABLE void setStringList(QString const &key, QStringList const &list);
    Q_INVOKABLE QVariant getStringList(QString const &key,
                                       QStringList const &defaultList) const;

    // Emit signals for all stored settings (used during initialization)
    void signalSettings();

signals:
    void settingChanged(QString const &key, QVariant const &value);
};

// Usage example: Application settings
Settings settings("corectrl");

// System tray settings
settings.setValue("sysTray", true);              // Enable system tray icon
settings.setValue("startOnSysTray", true);       // Start minimized to tray

// Window geometry persistence
settings.setValue("saveWindowGeometry", true);
settings.setValue("Window/main-x-pos", 100);
settings.setValue("Window/main-y-pos", 100);
settings.setValue("Window/main-width", 970);
settings.setValue("Window/main-height", 600);

// Retrieve settings with defaults
bool sysTrayEnabled = settings.getValue("sysTray", true).toBool();
int windowWidth = settings.getValue("Window/main-width", 970).toInt();

// Connect to setting changes
QObject::connect(&settings, &Settings::settingChanged,
    [](QString const &key, QVariant const &value) {
        qDebug() << "Setting changed:" << key << "=" << value;
    });
```

--------------------------------

### Session Class Interface and Usage

Source: https://context7.com/corectrl/corectrl/llms.txt

Defines the Session and ManualProfileObserver interfaces and demonstrates how to initialize the session and control manual profiles.

```cpp
// Session interface for profile coordination
class Session {
public:
    // Initialize session with system model
    void init(ISysModel const &model);

    // Manual profile control
    bool toggleManualProfile(std::string const &profileName);
    bool activateManualProfile(std::string const &profileName);
    bool deactivateManualProfile(std::string const &profileName);

    // Access to profile manager
    IProfileManager &profileManager() const;

    // Debug logging control
    void logProfileStack(bool enable);

    // Observer pattern for manual profile state changes
    void addManualProfileObserver(
        std::shared_ptr<ISession::ManualProfileObserver> observer);
    void removeManualProfileObserver(
        std::shared_ptr<ISession::ManualProfileObserver> observer);
};

// ManualProfileObserver for tracking profile state changes
class ManualProfileObserver {
public:
    virtual void toggled(std::string const &profileName, bool active) = 0;
};

// Usage example: Session profile coordination
Session session(profileApplicator, profileManager, profileViewFactory,
                helperMonitor, logProfileStack);
session.init(sysModel);

// Toggle a manual profile on/off
if (session.toggleManualProfile("Gaming Profile")) {
    std::cout << "Profile toggled successfully" << std::endl;
} else {
    std::cerr << "Profile not found or not a manual profile" << std::endl;
}

// Explicitly control manual profile state
session.activateManualProfile("High Performance");
session.deactivateManualProfile("Power Saving");

// Enable debug logging
session.logProfileStack(true);
```

--------------------------------

### Define Catch2 Main Library

Source: https://gitlab.com/corectrl/corectrl/-/blob/master/tests/CMakeLists.txt

Creates an object library for the test main entry point with necessary dependencies.

```cmake
# catch main
add_library(catch_main OBJECT "src/main.cpp")
target_include_directories(catch_main PRIVATE ${TESTS_INCLUDE_DIRECTORIES})
target_compile_definitions(catch_main PRIVATE ${TESTS_COMPILE_DEFINITIONS})
target_link_libraries(catch_main PRIVATE
  spdlog::spdlog
  Catch2::Catch2
  trompeloeil::trompeloeil
  ${ATOMIC_LIB}
)
```

--------------------------------

### Export and Import Profiles

Source: https://context7.com/corectrl/corectrl/llms.txt

Demonstrates how to use the ProfileManager to export and import profiles using the .ccpro format.

```cpp
CCPROParser parser;

// Export a profile
ProfileManager manager(/*...*/);
auto profileOpt = manager.profile("Gaming Profile");
if (profileOpt) {
    manager.exportTo("Gaming Profile", "/home/user/gaming.ccpro");
}

// Import a profile
if (manager.loadFrom("Imported Profile", "/home/user/gaming.ccpro")) {
    manager.save("Imported Profile");
    std::cout << "Profile imported successfully" << std::endl;
}
```

--------------------------------

### Configure CMake for Catch2 and trompeloeil

Source: https://gitlab.com/corectrl/corectrl/-/blob/master/tests/CMakeLists.txt

Sets up required packages, compile definitions, and include directories for the test suite.

```cmake
find_package(Catch2 3.0 REQUIRED)
find_package(trompeloeil 40 REQUIRED)

# Compile definitions
list(APPEND TESTS_COMPILE_DEFINITIONS
  ${3RDPARTY_DEFINITIONS}
  CATCH_CONFIG_FAST_COMPILE
  SPDLOG_ACTIVE_LEVEL=SPDLOG_LEVEL_TRACE
)

# include directories for all tests
list(APPEND TESTS_INCLUDE_DIRECTORIES
  ${3RDPARTY_INCLUDE_DIRECTORIES}
  ${PROJECT_SOURCE_DIR}/src
)
```

--------------------------------

### CoreCtrl Command Line Options

Source: https://context7.com/corectrl/corectrl/llms.txt

Use these options to control CoreCtrl's behavior, manage profiles, and debug. They can be used at startup or with a running instance.

```bash
# Display help and version information
corectrl --help
corectrl --version
```

```bash
# Start minimized to system tray
corectrl --minimize-systray
```

```bash
# Toggle a manual profile (activate if inactive, deactivate if active)
corectrl --toggle-manual-profile "Gaming Profile"
corectrl -m "Gaming Profile"
```

```bash
# Explicitly activate or deactivate a manual profile
corectrl --activate-manual-profile "Gaming Profile"
corectrl --deactivate-manual-profile "Gaming Profile"
```

```bash
# Toggle main window visibility on a running instance
corectrl --toggle-window-visibility
```

```bash
# Force a specific language/locale
corectrl --lang en_EN
corectrl -l es_ES
```

```bash
# Set helper process timeout (milliseconds, minimum 60000)
corectrl --helper-timeout 300000
corectrl -t 300000
```

```bash
# Enable/disable command logging for debugging
corectrl --enable-log-commands
corectrl --disable-log-commands
```

```bash
# Enable/disable profile stack logging for debugging
corectrl --enable-log-profile-stack
corectrl --disable-log-profile-stack
```

--------------------------------

### Settings Management API

Source: https://context7.com/corectrl/corectrl/llms.txt

Interface for persistent storage and retrieval of application preferences using QSettings.

```APIDOC
## Settings Management

### Description
Provides methods to store and retrieve application settings, including support for simple values and string lists.

### Methods
- **setValue(key, value)**: Stores a value associated with a key.
- **getValue(key, defaultValue)**: Retrieves a value for a key, returning a default if not found.
- **setStringList(key, list)**: Stores a list of strings.
- **getStringList(key, defaultList)**: Retrieves a list of strings.

### Request Example
// Store a setting
settings.setValue("sysTray", true);

// Retrieve a setting
bool sysTrayEnabled = settings.getValue("sysTray", true).toBool();
```

--------------------------------

### CoreCtrl ProfileManager C++ API

Source: https://context7.com/corectrl/corectrl/llms.txt

Interface for managing hardware configuration profiles, including creation, modification, activation, and storage. Requires system model and profile storage initialization.

```cpp
// ProfileManager interface for managing hardware profiles
class ProfileManager {
public:
    // Initialize the profile manager with system model
    void init(ISysModel const &model);

    // Get list of all profile names
    std::vector<std::string> profiles() const;

    // Get a specific profile by name
    std::optional<std::reference_wrapper<IProfile const>>
    profile(std::string const &profileName) const;

    // Create a new profile with specified info
    void add(IProfile::Info const &info);

    // Clone an existing profile
    void clone(IProfile::Info const &cloneInfo,
               std::string const &baseProfileName = IProfile::Info::GlobalID);

    // Remove a profile by name
    void remove(std::string const &profileName);

    // Activate or deactivate a profile
    void activate(std::string const &profileName, bool active);

    // Reset profile to defaults
    void reset(std::string const &profileName);

    // Restore profile from saved state
    void restore(std::string const &profileName);

    // Update profile information
    void update(std::string const &profileName, IProfile::Info const &newInfo);

    // Save profile to storage
    void save(std::string const &profileName);

    // Import/export profiles
    bool loadFrom(std::string const &profileName, std::filesystem::path const &path);
    bool exportTo(std::string const &profileName, std::filesystem::path const &path);

    // Check for unsaved changes
    std::vector<std::string> unsavedProfiles() const;
    bool unsaved(std::string const &profileName) const;
};

// Profile info structure
struct IProfile::Info {
    static constexpr std::string_view GlobalID{"_global_"};
    std::string name;           // Profile display name
    std::string exe;            // Executable name for automatic activation
    std::string iconURL;        // Custom icon URL
    bool hasCustomIcon{false};  // Whether profile uses custom icon
};

// Usage example: Creating and managing profiles
ProfileManager manager(defaultProfile, profileStorage);
manager.init(sysModel);

// Create a new gaming profile
IProfile::Info gamingInfo;
gamingInfo.name = "Gaming Profile";
gamingInfo.exe = "game.exe";  // Activate when this exe runs
manager.add(gamingInfo);

// Clone global profile for customization
IProfile::Info renderInfo;
renderInfo.name = "Rendering";
renderInfo.exe = "blender";
manager.clone(renderInfo, IProfile::Info::GlobalID);

// Save changes
manager.save("Gaming Profile");

```

--------------------------------

### CoreCtrl Command Line Interface

Source: https://context7.com/corectrl/corectrl/llms.txt

CoreCtrl provides various command line options for controlling the application behavior, managing manual profiles, and debugging. These options can be used both at startup and while an instance is already running.

```APIDOC
## CoreCtrl Command Line Options

### Description
CoreCtrl offers a set of command-line arguments to manage application behavior, profiles, and debugging.

### Usage
`corectrl [options]`

### Options
- `--help`: Display help and version information.
- `--version`: Display version information.
- `--minimize-systray`: Start the application minimized to the system tray.
- `--toggle-manual-profile "<Profile Name>"` or `-m "<Profile Name>"`: Toggles a manual profile (activates if inactive, deactivates if active).
- `--activate-manual-profile "<Profile Name>"`: Explicitly activates a manual profile.
- `--deactivate-manual-profile "<Profile Name>"`: Explicitly deactivates a manual profile.
- `--toggle-window-visibility`: Toggles the main window visibility on a running instance.
- `--lang <locale>` or `-l <locale>`: Forces a specific language/locale (e.g., `en_EN`, `es_ES`).
- `--helper-timeout <milliseconds>` or `-t <milliseconds>`: Sets the helper process timeout (minimum 60000ms).
- `--enable-log-commands`: Enables command logging for debugging.
- `--disable-log-commands`: Disables command logging.
- `--enable-log-profile-stack`: Enables profile stack logging for debugging.
- `--disable-log-profile-stack`: Disables profile stack logging.

### Examples
```bash
# Display help
corectrl --help

# Start minimized
corectrl --minimize-systray

# Toggle a profile
corectrl -m "Gaming Profile"

# Set language
corectrl -l es_ES

# Enable command logging
corectrl --enable-log-commands
```
```

--------------------------------

### Define Helper Source Lists

Source: https://gitlab.com/corectrl/corectrl/-/blob/master/src/helper/CMakeLists.txt

Appends source files and compile definitions for the helper components.

```cmake
list(APPEND HELPER_COMPILE_DEFINITIONS
  SPDLOG_ACTIVE_LEVEL=SPDLOG_LEVEL_TRACE
)

list(APPEND PROCESS_MONITOR_SRC
  pmon/processmonitor.cpp
  pmon/procpidsolver.cpp
  pmon/nlprocexecsocket.cpp
  pmon/nlprocexecmonitor.cpp
  pmon/processregistry.cpp
  pmon/appregistry.cpp
  pmon/msgdispatcher.cpp
  pmon/processeventconnector.c
)

list(APPEND SYSTEM_CONTROL_SRC
  sysctl/sysfswriter.cpp
  sysctl/msgreceiver.cpp
)
```

--------------------------------

### CPU Frequency Scaling Interface

Source: https://context7.com/corectrl/corectrl/llms.txt

Interface for controlling CPU frequency governors and Energy Performance Preference (EPP) hints.

```APIDOC
## CPU Frequency Scaling

### Description
Provides control over CPU frequency scaling governors and EPP hints, interacting with the Linux cpufreq subsystem.

### Parameters
#### Request Body
- **scalingGovernor** (string) - Required - The governor to set (e.g., performance, powersave, ondemand, conservative, schedutil).
- **eppHint** (string) - Optional - Energy Performance Preference hint (e.g., default, performance, balance_performance, balance_power, power). Requires powersave governor.

### Request Example
<CPU_CPUFREQ active="true">
  <scalingGovernor>powersave</scalingGovernor>
  <eppHint>balance_performance</eppHint>
</CPU_CPUFREQ>
```

--------------------------------

### Configure CPU Frequency Scaling

Source: https://context7.com/corectrl/corectrl/llms.txt

Defines the CPUFreq class interface for managing governors and Energy Performance Preference (EPP) hints. Requires interaction with the Linux cpufreq sysfs interface.

```cpp
#include "core/components/controls/cpu/cpufreq.h"

class CPUFreq : public Control {
public:
    static constexpr std::string_view ItemID{"CPU_CPUFREQ"};

    // Available governors typically include:
    // - performance (max frequency)
    // - powersave (min frequency, enables EPP)
    // - ondemand (dynamic scaling)
    // - conservative (gradual scaling)
    // - schedutil (scheduler-driven)

    class Importer : public IControl::Importer {
    public:
        virtual std::string const &provideCPUFreqScalingGovernor() const = 0;
        virtual std::optional<std::string> const &provideCPUFreqEPPHint() const = 0;
    };

    class Exporter : public IControl::Exporter {
    public:
        virtual void takeCPUFreqScalingGovernor(std::string const &governor) = 0;
        virtual void takeCPUFreqScalingGovernors(
            std::vector<std::string> const &governors) = 0;
        virtual void takeCPUFreqEPPHint(std::optional<std::string> const &hint) = 0;
        virtual void takeCPUFreqEPPHints(
            std::optional<std::vector<std::string>> const &hints) = 0;
    };

    CPUFreq(std::vector<std::string> &&scalingGovernors,
            std::string const &defaultGovernor,
            std::vector<std::unique_ptr<IDataSource<std::string>>>
                &&scalingGovernorDataSources,
            std::unique_ptr<IEPPHandler> &&eppHandler = nullptr) noexcept;

protected:
    std::string const &scalingGovernor() const;
    void scalingGovernor(std::string const &governor);
    std::vector<std::string> const &scalingGovernors() const;

    // Energy Performance Preference (requires powersave governor)
    // EPP hints: default, performance, balance_performance,
    //            balance_power, power
    std::optional<std::string> eppHint() const;
    std::optional<std::vector<std::string>> eppHints() const;
};

// Usage example: CPU frequency configuration
// sysfs paths:
// /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor
// /sys/devices/system/cpu/cpu*/cpufreq/energy_performance_preference

// Profile XML structure:
// <CPU_CPUFREQ active="true">
//   <scalingGovernor>performance</scalingGovernor>
// </CPU_CPUFREQ>

// With EPP (powersave governor required):
// <CPU_CPUFREQ active="true">
//   <scalingGovernor>powersave</scalingGovernor>
//   <eppHint>balance_performance</eppHint>
// </CPU_CPUFREQ>

// sysfs commands generated:
// echo "performance" > /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor
// echo "performance" > /sys/devices/system/cpu/cpu1/cpufreq/scaling_governor
// ... (for all CPU cores)
```

--------------------------------

### Implement CCPROParser for Profile Management

Source: https://context7.com/corectrl/corectrl/llms.txt

Defines the interface for parsing and saving .ccpro profile files.

```cpp
#include "core/ccpro/ccproparser.h"

class CCPROParser : public IProfileFileParser {
public:
    // File extension for CoreCtrl profiles
    std::string fileExtension() const override;  // Returns ".ccpro"

    // Load profile data from a .ccpro file
    std::optional<std::vector<char>>
    load(std::filesystem::path const &path,
         std::string const &internalDataName) override;

    // Save profile data to a .ccpro file
    bool save(std::filesystem::path const &path,
              std::vector<std::pair<std::string, std::vector<char>>> const &data)
        override;
};
```

--------------------------------

### Generate and Discover Test Executable

Source: https://gitlab.com/corectrl/corectrl/-/blob/master/tests/CMakeLists.txt

Compiles the test executable from source files and registers it with CTest for discovery.

```cmake
# test_* files
file(GLOB test_files "src/test_*.cpp")

# generate test_all executable
add_executable(test_all $<TARGET_OBJECTS:catch_main> ${test_files} ${3RDPARTY_SRC})
target_include_directories(test_all PRIVATE ${TESTS_INCLUDE_DIRECTORIES})
target_compile_definitions(test_all PRIVATE ${TESTS_COMPILE_DEFINITIONS})
target_link_libraries(test_all PRIVATE
  corectrl_lib
  Qt6::Core
  spdlog::spdlog
  $<$<BOOL:${units_FOUND}>:units::units>
  Catch2::Catch2
  trompeloeil::trompeloeil
  ${ATOMIC_LIB}
)

include(CTest)
include(Catch)
catch_discover_tests(test_all)
```

--------------------------------

### Profile Management API

Source: https://context7.com/corectrl/corectrl/llms.txt

The ProfileManager class provides an interface for creating, modifying, storing, and managing hardware configuration profiles within CoreCtrl.

```APIDOC
## ProfileManager API

### Description
The `ProfileManager` class is responsible for the lifecycle of hardware configuration profiles. It allows for initialization, retrieval, creation, modification, deletion, and persistence of profiles.

### Class `ProfileManager`

#### Methods
- `void init(ISysModel const &model)`: Initializes the profile manager with the system model.
- `std::vector<std::string> profiles() const`: Retrieves a list of all profile names.
- `std::optional<std::reference_wrapper<IProfile const>> profile(std::string const &profileName) const`: Gets a specific profile by its name.
- `void add(IProfile::Info const &info)`: Creates a new profile with the specified information.
- `void clone(IProfile::Info const &cloneInfo, std::string const &baseProfileName = IProfile::Info::GlobalID)`: Clones an existing profile.
- `void remove(std::string const &profileName)`: Removes a profile by its name.
- `void activate(std::string const &profileName, bool active)`: Activates or deactivates a profile.
- `void reset(std::string const &profileName)`: Resets a profile to its default settings.
- `void restore(std::string const &profileName)`: Restores a profile from its saved state.
- `void update(std::string const &profileName, IProfile::Info const &newInfo)`: Updates the information of an existing profile.
- `void save(std::string const &profileName)`: Saves a profile to persistent storage.
- `bool loadFrom(std::string const &profileName, std::filesystem::path const &path)`: Imports a profile from a specified file path.
- `bool exportTo(std::string const &profileName, std::filesystem::path const &path)`: Exports a profile to a specified file path.
- `std::vector<std::string> unsavedProfiles() const`: Returns a list of profiles with unsaved changes.
- `bool unsaved(std::string const &profileName) const`: Checks if a specific profile has unsaved changes.

### Struct `IProfile::Info`

#### Members
- `static constexpr std::string_view GlobalID{"_global_"}`: Identifier for the global profile.
- `std::string name`: The display name of the profile.
- `std::string exe`: The executable name for automatic profile activation.
- `std::string iconURL`: URL for a custom profile icon.
- `bool hasCustomIcon`: Flag indicating if the profile uses a custom icon.

### Usage Example
```cpp
// Assuming ProfileManager and ISysModel are available
ProfileManager manager;
ISysModel sysModel;

// Initialize the manager
manager.init(sysModel);

// Create a new profile
IProfile::Info gamingInfo;
gamingInfo.name = "Gaming Profile";
gamingInfo.exe = "game.exe";
manager.add(gamingInfo);

// Clone the global profile for customization
IProfile::Info renderInfo;
renderInfo.name = "Rendering";
renderInfo.exe = "blender";
manager.clone(renderInfo, IProfile::Info::GlobalID);

// Save the new profile
manager.save("Gaming Profile");

// Activate a profile
manager.activate("Gaming Profile", true);

// Check for unsaved changes
if (manager.unsaved("Rendering")) {
    manager.save("Rendering");
}
```
```

--------------------------------

### Session Management API

Source: https://context7.com/corectrl/corectrl/llms.txt

This section details the methods available for managing user sessions and profiles.

```APIDOC
## Session Management

The Session class coordinates profile activation based on running applications and manual user input. It monitors process execution and automatically applies the appropriate profile configurations.

### Methods

#### `init(ISysModel const &model)`

*   **Description**: Initializes the session with the system model.
*   **Method**: `void`
*   **Parameters**:
    *   `model` (ISysModel const &) - The system model to initialize with.

#### `toggleManualProfile(std::string const &profileName)`

*   **Description**: Toggles a manual profile on or off.
*   **Method**: `bool`
*   **Parameters**:
    *   `profileName` (std::string const &) - The name of the profile to toggle.
*   **Returns**: `true` if the profile was toggled successfully, `false` otherwise (e.g., profile not found or not a manual profile).

#### `activateManualProfile(std::string const &profileName)`

*   **Description**: Explicitly activates a manual profile.
*   **Method**: `bool`
*   **Parameters**:
    *   `profileName` (std::string const &) - The name of the profile to activate.

#### `deactivateManualProfile(std::string const &profileName)`

*   **Description**: Explicitly deactivates a manual profile.
*   **Method**: `bool`
*   **Parameters**:
    *   `profileName` (std::string const &) - The name of the profile to deactivate.

#### `profileManager() const`

*   **Description**: Provides access to the profile manager.
*   **Method**: `IProfileManager &`

#### `logProfileStack(bool enable)`

*   **Description**: Controls debug logging for the profile stack.
*   **Method**: `void`
*   **Parameters**:
    *   `enable` (bool) - `true` to enable logging, `false` to disable.

#### `addManualProfileObserver(std::shared_ptr<ISession::ManualProfileObserver> observer)`

*   **Description**: Adds an observer to track manual profile state changes.
*   **Method**: `void`
*   **Parameters**:
    *   `observer` (std::shared_ptr<ISession::ManualProfileObserver>) - The observer to add.

#### `removeManualProfileObserver(std::shared_ptr<ISession::ManualProfileObserver> observer)`

*   **Description**: Removes an observer from tracking manual profile state changes.
*   **Method**: `void`
*   **Parameters**:
    *   `observer` (std::shared_ptr<ISession::ManualProfileObserver>) - The observer to remove.

### Observer Interface

#### `ManualProfileObserver`

*   **Description**: Interface for observing manual profile state changes.

##### `toggled(std::string const &profileName, bool active)`

*   **Description**: Called when a manual profile's state is toggled.
*   **Parameters**:
    *   `profileName` (std::string const &) - The name of the profile that was toggled.
    *   `active` (bool) - `true` if the profile is now active, `false` otherwise.

### Usage Example

```cpp
// Usage example: Session profile coordination
Session session(profileApplicator, profileManager, profileViewFactory,
                helperMonitor, logProfileStack);
session.init(sysModel);

// Toggle a manual profile on/off
if (session.toggleManualProfile("Gaming Profile")) {
    std::cout << "Profile toggled successfully" << std::endl;
} else {
    std::cerr << "Profile not found or not a manual profile" << std::endl;
}

// Explicitly control manual profile state
session.activateManualProfile("High Performance");
session.deactivateManualProfile("Power Saving");

// Enable debug logging
session.logProfileStack(true);
```
```

--------------------------------

### Parse AMD GPU DPM States

Source: https://context7.com/corectrl/corectrl/llms.txt

Parses Dynamic Power Management states for GPU clock frequencies from sysfs files. Requires reading the relevant pp_dpm_sclk or pp_dpm_mclk file.

```cpp
#include "core/components/amdutils.h"

namespace Utils::AMD {

// Read GPU information via ioctl
template<typename Data>
bool readAMDGPUInfoSensor(int deviceFD, Data *value, std::uint32_t sensor);

template<typename Data>
bool readAMDGPUInfo(int deviceFD, Data *value, std::uint32_t query);

// Read VRAM size
bool readAMDGPUVRamSize(int deviceFD, units::data::megabyte_t *size);

// Parse DPM (Dynamic Power Management) states from pp_dpm_sclk/pp_dpm_mclk
std::optional<std::vector<std::pair<unsigned int, units::frequency::megahertz_t>>>
parseDPMStates(std::vector<std::string> const &ppDpmLines);

std::optional<unsigned int>
parseDPMCurrentStateIndex(std::vector<std::string> const &ppDpmLines);

// Parse power profile modes from pp_power_profile_mode
std::optional<std::vector<std::pair<std::string, int>>>
parsePowerProfileModeModes(std::vector<std::string> const &ppPowerProfileModeLines);

std::optional<int>
parsePowerProfileModeCurrentModeIndex(
    std::vector<std::string> const &ppPowerProfileModeLines);

// Parse overdrive clock and voltage settings from pp_od_clk_voltage
std::optional<std::vector<std::tuple<unsigned int, units::frequency::megahertz_t,
                                     units::voltage::millivolt_t>>>
parseOverdriveClksVolts(std::string_view controlName,
                        std::vector<std::string> const &ppOdClkVoltageLines);

std::optional<std::pair<units::frequency::megahertz_t, units::frequency::megahertz_t>>
parseOverdriveClkRange(std::string_view controlName,
                       std::vector<std::string> const &ppOdClkVoltageLines);

// Parse voltage curve for Vega20+ GPUs
std::optional<std::vector< 
    std::pair<units::frequency::megahertz_t, units::voltage::millivolt_t>>>
parseOverdriveVoltCurve(std::vector<std::string> const &ppOdClkVoltageLines);

// Parse voltage offset (RX 6000+)
std::optional<units::voltage::millivolt_t>
parseOverdriveVoltOffset(std::vector<std::string> const &ppOdClkVoltageLines);

// Parse fan curve for RDNA3+ (Linux 6.7+)
std::optional<std::vector<std::tuple<unsigned int, units::temperature::celsius_t,
                                     units::concentration::percent_t>>>
parseOverdriveFanCurve(std::vector<std::string> const &fanCurveLines);

// Feature detection helpers
bool hasOverdriveClkVoltControl(std::vector<std::string> const &data);
bool hasOverdriveVoltCurveControl(std::vector<std::string> const &data);
bool hasOverdriveVoltOffsetControl(std::vector<std::string> const &data);

} // namespace Utils::AMD

```

```cpp
// Usage example: Reading GPU DPM states
std::vector<std::string> ppDpmSclk = readFileLines("/sys/class/drm/card0/device/pp_dpm_sclk");
// Example content:
// 0: 500Mhz *
// 1: 800Mhz
// 2: 1200Mhz

auto states = Utils::AMD::parseDPMStates(ppDpmSclk);
if (states) {
    for (const auto &[
        index, freq] : *states) {
        std::cout << "State " << index << ": " << freq.value() << " MHz" << std::endl;
    }
}

auto currentIndex = Utils::AMD::parseDPMCurrentStateIndex(ppDpmSclk);
if (currentIndex) {
    std::cout << "Current state: " << *currentIndex << std::endl;
}

```

--------------------------------

### AMD Fan Curve Configuration

Source: https://context7.com/corectrl/corectrl/llms.txt

Interface for managing custom fan curves, including temperature-to-speed mapping and fan stop behavior.

```APIDOC
## AMD Fan Curve Interface

### Description
The FanCurve class provides methods to define and manage temperature-based fan speed curves for AMD GPUs.

### Parameters
#### Request Body (XML Serialization)
- **active** (boolean) - Required - Enables or disables the fan curve control.
- **fanStop** (boolean) - Required - Enables or disables the fan stop feature at low temperatures.
- **fanStartValue** (integer) - Required - The fan speed percentage when exiting fan stop mode.
- **curve** (array) - Required - A collection of points mapping temperature (Celsius) to speed (percentage).

### Request Example
<AMD_FAN_CURVE active="true">
  <fanStop>true</fanStop>
  <fanStartValue>30</fanStartValue>
  <curve>
    <point temp="30" speed="20"/>
    <point temp="50" speed="40"/>
    <point temp="70" speed="70"/>
    <point temp="85" speed="100"/>
  </curve>
</AMD_FAN_CURVE>
```

--------------------------------

### AMD Power Management Control Classes

Source: https://context7.com/corectrl/corectrl/llms.txt

Defines C++ classes for managing AMD GPU power cap, power profiles, and overdrive settings. These classes abstract interactions with underlying hardware controls.

```cpp
#include "core/components/controls/amd/pm/advanced/powercap/pmpowercap.h"
#include "core/components/controls/amd/pm/advanced/powerprofile/pmpowerprofile.h"
#include "core/components/controls/amd/pm/advanced/overdrive/pmoverdrive.h"

namespace AMD {

// Power cap control (TDP limit)
class PMPowerCap : public Control {
public:
    static constexpr std::string_view ItemID{"AMD_PM_POWERCAP"};

    class Importer : public IControl::Importer {
    public:
        virtual units::power::watt_t providePMPowerCapValue() const = 0;
    };

    class Exporter : public IControl::Exporter {
    public:
        virtual void takePMPowerCapValue(units::power::watt_t value) = 0;
        virtual void takePMPowerCapRange(units::power::watt_t min,
                                         units::power::watt_t max) = 0;
    };

    PMPowerCap(std::unique_ptr<IDataSource<unsigned long>> &&powerCapDataSource,
               units::power::watt_t min, units::power::watt_t max,
               std::optional<units::power::watt_t> defaultValue = {}) noexcept;

protected:
    units::power::microwatt_t value() const;
    void value(units::power::microwatt_t value);
    units::power::microwatt_t min() const;
    units::power::microwatt_t max() const;
};

// Power profile mode control
class PMPowerProfile : public Control {
public:
    static constexpr std::string_view ItemID{"AMD_PM_POWER_PROFILE"};

    // Available modes typically include:
    // - BOOTUP_DEFAULT (0)
    // - 3D_FULL_SCREEN (1)
    // - POWER_SAVING (2)
    // - VIDEO (3)
    // - VR (4)
    // - COMPUTE (5)
    // - CUSTOM (6)

    class Importer : public IControl::Importer {
    public:
        virtual std::string const &providePMPowerProfileMode() const = 0;
    };

    class Exporter : public IControl::Exporter {
    public:
        virtual void takePMPowerProfileMode(std::string const &mode) = 0;
        virtual void takePMPowerProfileModes(std::vector<std::string> const &modes) = 0;
    };

protected:
    void mode(std::string const &mode);
    std::string const &mode() const;
    std::vector<std::string> const &modes() const;
};

// Overdrive control group for advanced GPU tuning
class PMOverdrive : public ControlGroup {
public:
    static constexpr std::string_view ItemID{"AMD_PM_OVERDRIVE"};

    // Contains sub-controls for:
    // - Frequency range (SCLK/MCLK min/max)
    // - Frequency + Voltage states
    // - Voltage curve
    // - Voltage offset

    PMOverdrive(std::unique_ptr<IDataSource<std::string>> &&perfLevelDataSource,
                std::unique_ptr<IDataSource<std::vector<std::string>>>
                    &&ppOdClkVoltDataSource,
                std::vector<std::unique_ptr<IControl>> &&controls) noexcept;
};

} // namespace AMD

```

--------------------------------

### Parse AMD GPU Overdrive Voltage Curve

Source: https://context7.com/corectrl/corectrl/llms.txt

Parses the voltage curve settings for Vega20+ GPUs from the pp_od_clk_voltage sysfs file. This function extracts pairs of frequencies and their corresponding voltages.

```cpp
// Reading overdrive settings
std::vector<std::string> ppOdClkVolt = readFileLines(
    "/sys/class/drm/card0/device/pp_od_clk_voltage");
// Example content for Vega20+:
// OD_SCLK:
// 0: 800Mhz
// 1: 2100Mhz
// OD_MCLK:
// 1: 875Mhz
// OD_VDDC_CURVE:
// 0: 800Mhz 750mV
// 1: 1400Mhz 850mV
// 2: 2100Mhz 1100mV

auto voltCurve = Utils::AMD::parseOverdriveVoltCurve(ppOdClkVolt);
if (voltCurve) {
    for (const auto &[
        freq, volt] : *voltCurve) {
        std::cout << freq.value() << " MHz @ " << volt.value() << " mV" << std::endl;
    }
}

```