DOCSEARCHbyAlgolia
Submit Docs

CPUFriend Documentation

repository·master·Indexed 20 days ago

https://github.com/acidanthera/cpufriend

A Lilu plug-in that enables dynamic power management data injection for CPUs not natively supported by the macOS kernel (XNU). It hooks the configResourceCallback() function from ACPI_SMC_PlatformPlugin or X86PlatformPlugin to provide customized power management information.

Tokens
1.1K
Snippets
1
Records
7
Agent score
19%

What's inside CPUFriend

  1. Overview of CPUFriend

    master

    CPUFriend is a Lilu plug-in designed for dynamic power management data injection. It is used to provide power management information to the macOS kernel (XNU) when the CPU is not natively supported.

    Note: This kext is often unnecessary if your CPU is already natively supported by the macOS kernel.

  2. Install CPUFriend

    master

    Prerequisites

    • Do not modify ACPI_SMC_PlatformPlugin or X86PlatformPlugin.

    Installation Methods

    1. Bootloader Injection (Highly Recommended): Inject the data via your bootloader.
    2. System Folders: If installing to /System/Library/Extensions or /Library/Extensions, you may require LiluFriend to ensure full functionality. However, installing to system folders is strongly discouraged.

    How it works

    CPUFriend hooks the configResourceCallback() function from ACPI_SMC_PlatformPlugin or X86PlatformPlugin. If no customized data is provided, CPUFriend does nothing and the original data is used.

  3. Compilation requirements for CPUFriend

    master

    To successfully compile CPUFriend, you must use the latest versions of the following dependencies:

    Debugging Setup: When debugging, ensure that:

    1. The debug version of Lilu.kext and the MacKernelSDK project folder are placed in the same directory as CPUFriend.
    2. You use the debug versions of both Lilu and CPUFriend together.

  4. Combine ssdt_data.dsl with an SSDT from ssdtPRGen.sh

    master

    If you are using an SSDT generated by ssdtPRGen.sh, you must manually combine the data from ssdt_data.dsl into that SSDT.

    Steps

    1. Generate ssdt_data.dsl using ./ResourceConverter.sh --acpi /path/to/file.
    2. Open the SSDT generated by ssdtPRGen.sh in a text editor.
    3. Locate the Method (_DSM, 4, NotSerialized) block.
    4. Copy the "cf-frequency-data" entry from your generated ssdt_data.dsl and paste it into the _DSM method in the ssdtPRGen.sh SSDT.

    Example Structure

    	// Context of the SSDT generated by ssdtPRGen.sh
	Method (_DSM, 4, NotSerialized)
	{
		if (LEqual (Arg2, Zero))
		{
			Return (Buffer (One)
			{
				0x03
			})
		}

		Return (Package ()
		{
			"plugin-type", 
			One,

			// Paste the entry from ssdt_data.dsl here
			"cf-frequency-data",
			Buffer ()
			{
				// Data from ssdt_data.dsl
			}
		})
	}

  5. Important usage warnings for CPUFriend

    master

    CPUFriend is most likely NOT required if you are unsure whether to use it.

    In most cases, native CPU power management data from ACPI_SMC_PlatformPlugin or X86PlatformPlugin works out of the box. Before using CPUFriend for data customization, consider these alternatives:

    • SMBIOS Changes: Changing SMBIOS can result in different data being used, which is often a more reasonable approach.
    • Analyzers: Use the analyzer scripts for FrequencyVectors provided in the Tools directory to understand your current data.
    • Avoid Performance Breaking: Do not use CPUFriend to break native CPU performance tuning mechanisms, such as patching LFM (Low Frequency Mode).

    Note: CPUFriend only handles data injection. If you need manual performance tuning, use external scripts like CPUFriendFriend or one-key-cpufriend. Support for those scripts is not provided by the CPUFriend repository.

  6. Available CPUFriend kernel flags

    master

    You can use the following kernel flags to control CPUFriend behavior:

    FlagDescription
    -cpufdbgEnables debug logging (Note: ONLY available in DEBUG binaries).
    -cpufoffDisables CPUFriend entirely.
    -cpufbetaEnables CPUFriend on unsupported OS versions.

  7. Generate data using ResourceConverter.sh

    master

    The Tools/ResourceConverter.sh script generates either a CPUFriendDataProvider.kext or an ssdt_data.dsl file from a provided input file.

    Input Requirements:

    • The input file must be a complete plist extracted from the Resources folder inside ACPI_SMC_PlatformPlugin or X86PlatformPlugin.
    • The plist may require certain modifications (e.g., replacing a raw FrequencyVectors entry).

    Output Location: The generated files are placed in the current working directory (check with pwd).

    # Create a CPUFriendDataProvider.kext
./ResourceConverter.sh --kext /path/to/input_plist

# Create an ssdt_data.dsl
./ResourceConverter.sh --acpi /path/to/input_plist