Instructions.md

CPUFriend Installation & Usage

WARNING

CPUFriend is most likely NOT required when not sure whether or not to use it.

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. If possible, changing SMBIOS, which results in other data being used, can be more reasonable. In Tools, several analyzer scripts for FrequencyVectors are provided as a good beginning. Also, CPUFriend should not be used to break the native CPU performance tuning mechanism by patching e.g. LFM (Low Frequency Mode). In case of necessity for manual performance tuning, the following scripts might be used:

• CPUFriendFriend by corpnewt
• one-key-cpufriend by stevezhengshiqi

Nevertheless, NO support will be provided from the side of CPUFriend as it only handles data injection. Please file issues at the corresponding repositories instead.

While such automated scripts bring convenience, it is, however, still necessary to understand the meaning of these modifications. Otherwise once again, consider not using CPUFriend.

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

First and foremost, both ACPI_SMC_PlatformPlugin and X86PlatformPlugin should remain untouched. Injection via bootloader is highly recommended. When installing to system folders (i.e. /System/Library/Extensions or /Library/Extensions), LiluFriend may be required to ensure full functionality. This is, however, strongly discouraged.

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: For simplicity, CPUFriendDataProvider.kext is always preferred. 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.

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 is produced in 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 in lieu of e.g. a raw FrequencyVectors entry.

Data Combination

1. Generate a correct copy of CPUFriendDataProvider.kext 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
	//