Instructions.md

CPUFriend Installation & Usage

WARNING

In most cases the native CPU power management data from ACPI_SMC_PlatformPlugin or X86PlatformPlugin work out of the box. Do NOT use CPUFriend for data customization until one knows clearly what power management data really is. Instead, changing SMBIOS, which results in other data being used, can be more reasonable. FrequencyVectors.bt can be a good start for the analysis of FrequencyVectors. Another thing worth mentioning is that CPUFriend should NOT be used only for patching LFM (Low Frequency Mode), particularly on mobile models including MacBook series.

Technical background

• Function configResourceCallback() from ACPI_SMC_PlatformPlugin or X86PlatformPlugin is hooked so as to handle customized CPU power management data from user. If nothing is provided, CPUFriend does nothing and the original data is to be used as if this kext is not installed.

Installation

Injection via bootloader is highly recommended, or LiluFriend may be needed to ensure full functionality when installing to system folders such as /Library/Extensions. Both ACPI_SMC_PlatformPlugin and X86PlatformPlugin should remain untouched.

Available kernel flags

Add -cpufdbg to enable debug logging (ONLY available in DEBUG binaries).

Add -cpufoff to disable CPUFriend entirely.

Add -cpufbeta to enable CPUFriend on unsupported OS versions.

Configuration

Tools/ResourceConverter.sh is meant to generate a working copy of either CPUFriendDataProvider.kext or ssdt_data.dsl, from which CPUFriend reads data.

NOTE: Where there is another SSDT generated by ssdtPRGen.sh, combination between ssdt_data.dsl and the SSDT table produced by this script is required. See Data Combination for further details. For simplicity, CPUFriendDataProvider.kext is preferred in this case.

Usage of ResourceConverter.sh

--kext /path/to/file Create CPUFriendDataProvider.kext with information provided by file.

--acpi /path/to/file Create ssdt_data.dsl with information provided by file.

NOTE:

• The kext/ssdt produced is located at the current working directory that can be revealed with pwd.
• file should be a complete plist from Recources inside ACPI_SMC_PlatformPlugin or X86PlatformPlugin with certain modifications (Otherwise why is CPUFriend even required?) instead of something like a raw FrequencyVectors entry.

Data Combination

1. Generate a correct copy of ssdt_data.dsl with ./ResourceConverter.sh --acpi /path/to/file.
2. Open SSDT previously generated by ssdtPRGen.sh, and search for Method (_DSM, 4, NotSerialized) in a text editor.
3. Paste "cf-frequency-data" entry from ssdt_data.dsl to the SSDT generated by ssdtPRGen.sh. A glance at the final work looks as follows.

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

		Return (Package () // size removed
		{
			"plugin-type", 
			One,

			//
			// Paste it from ssdt_data.dsl
			//
			"cf-frequency-data",
			Buffer () // size removed
			{
				// Data from ssdt_data.dsl
			}
		})
	}
	//
	// Context of the SSDT generated by ssdtPRGen.sh
	//