View attachment 350539
An iDiot's Guide To Lilu and its Plug-in's
Last Update: 29th January 2019 (Correct typo's in DRM section)
Warning: Make sure to use the latest version of Lilu and all plug-in's.
About this Guide
This guide is written as a helping hand to those users who have some understanding of using legacy hackingtosh methods but are considering using Lilu as a means to migrate to Mojave or using Lilu in place of traditional/legacy MacOS patching methods.
Before we go any further I should state for the record that I have no direct affiliation with Lilu, my first encounter with it was in early 2017 when i needed to resolve an issue with the refresh rate of the 4K display on my laptop. Since then I've followed its development and progress and I now consider Lilu to be one of the most useful tools in the Hackingtosh community toolbox.
What is Lilu ?
Lilu is a MacOS "Patching Engine " that allows for on-the-fly patching of the kernel and system extensions, Lilu offers a number of benefits over more traditional hackingtosh methods, in summary these are :-
- Does not depend on a bootloader
- Works in Recovery mode and the MacOS Installer
- Supports a symbolic patching engine
- Enables API access to the kernel and system extensions
- Allows modification of running processes
Lilu has been around for a few years and much like when Clover first appeared on the scene it has taken a while for it to become mature and stable enough for mainstream use. On its own Lilu does nothing, it needs to be used with plug-in's.
Lilu has its own
SDK meaning that anyone with the right skills can write a plug-in, as such it has gained a following of dedicated developers and users and has become the preferred 'Patching Engine' for many Hackingtosh gurus.
The three most popular
Lilu plug-in's which we will discuss in this guide are:-
- WhateverGreen --> Deals with patching the kernel and system extensions for GPU support (Intel/AMD/Nvidia)
- AppleALC --> Dynamic patching of AppleHDA for non officially supported codecs
- AirportBrcmFixup --> Various patches for Broadcom Airport Wi-Fi cards
Tip: Click on the above links to jump directly to the appropriate chapter in the guide.
Each of these plug-in's is covered in detail in its own section of this guide below, for a for a full list of all the available
Lilu plug-ins and where to get them you can use this
link.
Important Note: All of the above Lilu plug-in's are fully self contained solutions and will (in most cases) replace all legacy Clover patches and Injection/Enabler kext's for a plug-in's given purpose, as such you should remove any existing Clover patches and kext's that have been already installed for a plug-in's purpose ... for example when installing AppleALC you should remove (or disable) all Clover AppleHDA patches and uninstall any HDA Enabler, patching or dummy kext's. Failure to remove associated patches and kext's can result in unpredictable and often unstable results.
Each plugin has its own documentation and linked support threads that are usually detailed in the readme.md file or the Wiki on a plug-in's Git-Hub project page. You should familiarise yourself with these resources as they list the best places to get more specific help.
Binary releases of
Lilu and plug-in's are downloaded by visiting the appropriate Git-Hub project and clicking on the
Releases tab, you'll be shown the release history with the most recent version available at the top of page. Most users should download the latest
Release version, in some rare cases you may need to download the
Debug version or an earlier release.
In some very rare cases you may need to download Lilu's or a plug-in's source code and compile it yourself using Xcode, this will only need to be done when a specific fix or support for a new device has been added to the project and a public binary release is not yet available. When compiling a Plug-in you will need to copy the latest Debug version of Lilu into the project resources folder as all plugins need to be compiled against Lilu's API.
Lilu and its plug-in's can be used on any Hackingtosh system running MacOS Sierra or later and is recommended for MacOS Mojave.
How to Install
Lilu and it's plug-in's are provided as MacOS kext's and should all be installed in /Library/Extensions folder, you may read in some of the support threads of people installing everything in Clovers Kexts/Other folder but this should only be done for testing or development purposes. Installing them in /Library/Extensions will ensure that they are cached by the kernel and available to MacOS, this is the preferred and Apple endorsed location for all 3rd party MacOS kext's including FakeSMC. For a more detailed explanation of why we should install kexts in /Library/Extensions and not use Clover to Inject all the kexts see
this guide.
Note: You should also have FakeSMC installed in Clovers Kexts/Other folder so that clover can inject FakeSMC if you need to boot the installer or MacOS recovery, this is the only kext you really need in Clovers Kexts/Other folder all other 3rd party kext's should be installed in /Library/Extensions.
You can download Lilu and the Plug-in's you need using the following links :-
Each link will take you to the appropriate Git-Hub page, click on "
Releases" on the main page and download the latest release version, unzip each archive and copy all of the kexts into one place.
First we need to make sure that MacOS is allowed to load unsigned kexts/drivers ...
1. Make sure you have the boot argument
kext-dev-mode=1 :-
2. And that you set BooterConfig and CsrActiveConfig in Clover
RTVariables section to the following values :-
If your not familiar with using terminal/console commands to install kext's into the /Library/Extensions folder and rebuilding the caches then I recommend using the following method:-
Download
KextBeast which is available in the
downloads section, copy all the kext's you want to install onto the desktop and run the KextBeast pkg file, click on continue a few times, enter your admin password if prompted and accept the usual notices until you get the option to select the install target. Select /Library/Extensions and click on Continue.
View attachment 350155
KextBeast will install the kext's that you placed on the desktop into the target Extensions folder. Once KextBeast has done its work it will offer you the option of keeping the pkg or deleting it. I generally click on keep as i'm always trying new and different versions of kext's and KextBeast is a quick and easy way to do the job.
Once KextBeast has finished I recommend running version 2.6.6 of cVad's
Kext Utility (click
here to download) which will repair any broken kext permissions and rebuild the caches. Simply run the app and enter your admin password when prompted, then wait while Kext Utility does it's work. You will know when it's finished once you see "Quit" in black text at the bottom of the app window.
View attachment 359368
Note: Do not use Kext Utility to install Lilu and its plug-in's as it does not support installing kext's into /Library/Extensions, it does however do a much better job of repairing the kext permissions and rebuilding the caches than KextBeast.
Once Kext Utility has finished reboot your system.
For more information on installing kexts and why we use /L/E see the
Install Kexts Guide.
WhatEverGreen
When it was first released WhatEverGreen only supported AMD GPU's, other GPU types such as Nvidia and Intel IGPU's along with some other display related patches where supported by Lilu using separate specific plug-ins. However, as of mid 2018 WhatEverGreen merges the existing AMD GPU Support with all of the following plugins:-
As such WhatEverGreen (WEG) is now the one-stop solution for all GPU and Display related MacOS patching.
Important: It should be noted that as of July 2018 all of the above plug-in's are depreciated and are no longer supported. Use of them in conjunction with WhatEverGreen or the current version of Lilu could result in Kernel Panics or abnormal MacOS behaviour.
For AMD and Nvidia users, WhatEverGreen contains a number of default fixes and patches such as the common black screen on boot up issue, simply installing WhatEverGreen should be enough to enable the DGPU and get things working, for more experienced users there are a number of optional boot arguments that can be used with AMD and Nvidia GPU's which are detailed in the WhatEverGreen
readme.md and
manual.
For IGPU only or mixed GPU (DGPU + IGPU) systems, WhatEverGreen offers us a quick and easy method of enabling and customising the IGPU for MacOS than the legacy methods of using Clover or customised Intel driver/framebuffer kext's.
Important: If you have a laptop with dual GPU's (DGPU + IGPU) with switched graphics, IE the DGPU is routed through the IGPU then you must disable the DGPU first before continuing, see
RehabMans guide for more info.
Prerequisites
Installing WhatEverGreen will take care of renaming all of the required ACPI identities for us so if you have any of the following Clover ACPI Fixes/Renames in your config.plist you should remove or disable them:-
- Change/Rename GFX0 to IGPU
- Change/Rename PEG0 to GFX0
- Change/Rename HECI to IMEI
The above Clover ACPI Fixes/Renames use a global/generic method of renaming the ACPI identities in the DSDT that can cause problems for us later on. WhatEverGreen finds the DSDT code that requires new ACPI identities using device specific identifiers and thus does a much better job.
Note: There is one exception to the above rule, if you have a laptop and are using @rehabmans method to enable the backlight control then you should keep the Change/Rename GFX0 to IGPU ACPI fix in place otherwise the code in the hot-patch SSDT-PNLF.aml will not work correctly.
WhatEverGreen Configuration
WhatEverGreen is configured using Device Properties, this is a relatively new method of defining custom properties in a devices ioreg directory tree using Clover and was added specifically at the request of the Lilu developers who work closely with the Clover developers.
For a bit more information on Device Properties see
this post in the Clover dev blog.
A Device Property is defined in Clover's config.plist "
Devices" section, a property consists of a name and a data value assigned against a device's PCI path. Both the PCI path and the property name(s) are defined as <key> types, the value of a property is defined as a base64 <data> type . You can add Device Properties by directly editing your config.plist file using a code or text editor, or you can use a plist editor such as Xcode or PlistEdit-Pro. Clover Configurator now also supports Device Properties, use whichever method you are most familiar with.
Getting the IGPU Device Properties
In order to find out which Device Properties and values are needed
@headkaze has written a very handy little app for us called
Hackingtool (formally called Intel FB-Patcher) that will generate the IGPU Device Properties patch code for you. Simply download, unzip and run
Hackingtool, the first and most important thing to do is to check that the
PlatformID is correct for your Intel IGPU.
View attachment 350131
Note-1: If
Hackingtool correctly identifies your CPU Generation but the
PlatformID drop down menu is empty and the
Framebuffer and
Connector tabs show no data then you should click on "
FrameBuffer" in
Hackingtool top menu and select the MacOS version you are using.
View attachment 355437
Note-2: If
Hackingtool is unable to identify your CPU Generation automatically and you see
??? next to '
IntelGen' or Hackingtool incorrectly selects the wrong type of CPU then you can manually select the correct CPU Generation using the dropdown menu :-
View attachment 378880
Important: Hacking tool has recently gone through a change to its user interface, the examples in this guide are from the previous version of the UI. The only real difference is the top icon/menu now selects the mode for Hackingtool and the lower menu bar selects the sub-function of the mode. In the following examples you should use Hackingtool in the Intel IGPU mode which is the first icon on the top icon icon/menu and the sub function is now selected using the bottom menu (where as in the previous version the sub-function menu was at the top of the UI.
View attachment 384720
The first time you run
Hackingtool it will detect your IGPU and select the default
PlatformID for it, in many cases this will be wrong so we need to manually select the correct one. With the
General tab selected, the type of IGPU detected will be displayed next to
GPU Info and details of the the selected
PlatformID and matching System Definitions (SMBIOS) will be displayed next to to
Framebuffer Info. For example if I run the latest build of
Hackingtool on my 2017 HP Spectre X360 laptop by default
Hackingtool selects
0x591B0000 as a
PlatformID and suggests MacBookPro 14,3 as the System Definition (SMBIOS) to use.
View attachment 361324
This shows conflicting information, the IGPU is correctly detected and displayed as a HD 620 IGPU in the
GPU Info section but the
Framebuffer Info shows that
0x591B0000 is for a HD 630 IGPU so we know that the default of
0x591B0000 would be a poor choice, we can change this by using the
PlatformID dropdown menu to select the correct one, if you don't already know the
PlatformID you need then select each one in turn from the drop down menu until you find one that matches your systems specification. For my HP Spectre X360 laptop I already know that I need
0x59160000 so i select it using the dropdown menu.
View attachment 361325
We can now see that the
Framebuffer Info matches the
GPU Info which in the case of my HP Spectre X360 laptop is a Mobile HD620 IGPU, and that the recommended System Definition (SMBIOS) is MacBookPro 14,2 which i'm already using.
Pro Tip: I recommend using
Post#2 of
@headkaze's guide which lists the complete details of each
PlatformID along with IGPU specifics grouped in CPU Generation order. This will help you choose the correct
PlatformID for your system, once you have identified the
PlatformID you need you can select it using the
Hackingtool PlatformID drop down menu.
Important: Always use the correct System Definition (SMBIOS) for the selected
PlatformID,
Hackingtool will in many cases display the recommended SMBIOS in the lower section of the
General tab. Use of a non matching
PlatformID and System Definition (SMBIOS) can result in abnormal MacOS behaviour.
Note: There are a few
PlatformID's where
Hackingtool will not list any recommend System Definitions (SMBIOS) or show "
Unknown" next to "
Model(s)" in the lower section of the
General tab, this means that there are no matching Mac Models using that combination of CPU, IGPU & PlatformID however the IGPU
PlatformID is still valid and should work. If possible I recommend selecting an alternative
PlatformID that has a framebuffer that matches your IGPU and also has a recommended/matching System Definition (SMBIOS).
View attachment 362188View attachment 362189
If you can't find a
PlatformID that matches your IGPU with a recommended System Definition (SMBIOS) it does not mean that things wont work, it just means that you'll have to take your best guess at finding the nearest matching SMBIOS to your Hackintosh hardware, a good tool that can help you make this decision is
MacTracker or use
Post#2 of
@headkaze's guide.
Headless PlatformID's
Another reason that desktop users with dual (DGPU + IGPU) systems my want to over-ride
Hackingtool suggested
PlatformID is if you want to use your IGPU in headless mode.
Genuine desktop Mac's with dual GPU configurations such as most iMacs and some Mac Mini systems use a headless
PlatformID to inform MacOS that the IGPU does not have any physical display connectors but it is still available to MacOS for IGPU hardware accelerated features such Airplay Display Mirroring and Video Encoding/Decoding (Intel Quick Sync)
Note: Systems with workstation class CPU's (Intel Xeon) do not have a IGPU as such you should not attempt to set a Headless PlatformID.
If you don't need to use a headless configuration, you can skip down to the next section titled
WEG Configuration Continued.
Headless IGPU Configuration
If your primary display adaptor is a DGPU such as Nvidia or AMD and you have a supported IGPU then using a headless
PlatformID will allow your Hackingtosh system to be more stable and behave much more like a genuine Mac with access to IGPU hardware accelerated features.. Use of this mode requires that the IGPU is
enabled in your BIOS and that the DGPU is set as the
primary display adaptor, you must also use the correct Mac System Definition (SMBIOS) that supports dual GPU configurations and matches your CPU & IGPU type.
Recommended desktop System Definitions (SMBIOS) for headless
PlatformID's are :-
- Coffee & Kaby Lake CPU = SysDef: imac18,x
- SkyLake CPU = SysDef: imac17,x
- Haswell CPU SysDef: imac14,x or imac15,x
- Ivy Bridge CPU SysDef: imac13,x or macmini6,x
- Sandy Bridge CPU = SysDef: imac12,x or macmini5,x
Note: If your CPU, IGPU and selected headless
PlatformID match a known Mac Configuration
Hackingtool will display the recommended System Definition(s) (SMBIOS) in the lower section of the
General tab.
Currently known headless
PlatformID's are :-
- Coffee Lake CPU - Only for MacOS 10.13.6 (17G2112+) and 10.14.X
- UHD-630 IGPU = 0x3E920003 or 0x3E910003
- Kaby Lake CPU
- HD-630 IGPU = 0x59120003
- Unknown = 0x59180002 (not recommended)
- SkyLake CPU
- HD-510 IGPU = 0x19020001
- GT2f IGPU = 0x19170001
- HD-530 IGPU = 0x19120001
- Iris Pro 580 = 0x19320001
- Haswell CPU
- HD-4600 IGPU = 0x04120004 or 0x0412000B
- Ivy Bridge CPU
- HD-4000 IGPU = 0x01620006 or 0x01620007
- Sandy Bridge CP
- HD-3000 IGPU = 0x00030030
You can confirm that a selected
PlatformID is headless in
Hackingtool by clicking on the
Connectors tab, all entries should have the following values:-
- index = -1
- bus id = 0x00
- pipe = 0
- type = dummy
Additionally when using
Hackingtool Version 1.71 onwards you should also see a 'Headless' Icon
Example using the
Haswell headless
PlatformID of
0x0412000B
View attachment 378877
Note-1: Headless IGPU mode only works well on dual GPU (DGPU + IGPU) desktop systems, it will not work on dual GPU laptops as both GPU's output to the same display panel, as such you should always disable the DGPU, see
RehabMans guide for more info.
Note-2: As already stated, use of a headless
PlatformID is only guaranteed to work when used in-conjunction with one of the recommended Mac System Definitions (SMBIOS), use of other System Definitions may result in an unstable system.
Note-3: When using a headless
PlatformID the IGPU will no longer show up in System Information even though it is enabled in your BIOS, this is normal and is one way of confirming that the headless IGPU mode is activated.
Note-4: If your system is equipped with one or more working Thunderbolt 3 port(s) and you have dGPU + Headless IGPU then you will need to enable the "
Above 4G Decoding" option in your motherboards BIOS.
Note-5: If you want to check everything is correct then use
IORegistryExplorer and search for "IGPU", you should see the IGPU entry with
AAPL, ig-platform-id set to the headless
PlatformID (in reverse byte order) and a matching model description :-
View attachment 370429
Note-6: You can check which codec's Intel Quick Sync supports on your IGPU using the demo (or full) version of
VideoProc. Once installed open VideoProc and click on the
Setting icon on the main page, then click on the
Options button next to "Hardware accelerate engine" :-
View attachment 370606
You should see something like this:-
View attachment 370571
Sandy Bridge CPU's and above will support hardware H.264 encode and decode, if you have Kaby Lake or later then you should also see hardware support for HEVC (H.265).
You can also use the attached VDADecoderChecker App to confirm that your IGPU is configured correctly for hardware video decoding.
WEG configuration Continued
You can work through the other tabs and options in
Hackingtool to view all the currently selected settings and change any if needed. Most users wont need to change anything at this point but if you are curious about the settings WhatEverGreen uses for a particular
PlatformID take a look at
post#2 of the WEG guide
.
When everything is how you want it, click on the
Patch tab and then on the
Generate Patch button. In a lot of cases WhatEverGreen only needs
AAPL,ig-platform-id (or
AAPL,snb-platform-id on Sandy Bridge systems) to be injected as a Device Property in order to get working video on the IGPU's default display. In the following example I've run
Hackingtool on my 2017 HP Spectre X360 laptop which has an Intel HD-620 IGPU and is using a "
PlatformID"of "
0x59160000".
View attachment 350133
Examples Note-1: In some of these examples you will see the Device Property "
device-id" which can be thought of as a IGPU generation identifier (it will always be the first two bytes of the PlatformID in reverse byte order followed by four zero's). The need to set/inject this property is in many cases not necessary, and some users have reported that it can cause problems which is why
Hackingtool no longer automatically generates this value. However other users have reported that without this property their system does not work correctly so the need for it is on a by use basis. If you want
Hackingtool to generate the patch code for the "
device-id" Device Property you can do so by selecting the option in the
Advanced sub-tab on the
Patch page of
Hackingtool.
Examples Note-2: You will also see a second PCI root path in the Clover Configurator and Plist Edit examples below, this is the PCI Root path of my Audio Codec and has nothing to do with with IGPU Device Properties - see the AppleALC section of the guide for more info.
You can now copy and paste the patch code snippet into your config.plist taking care to keep the correct <dict> structure, using the above example this is what the Device Properties patch code looks like in my config.plist.
Code:
<key>Devices</key>
<dict>
<key>Properties</key>
<dict>
<key>PciRoot(0x0)/Pci(0x2,0x0)</key>
<dict>
<key>AAPL,ig-platform-id</key>
<data>
AAAWWQ==
</data>
</dict>
</dict>
</dict>
Note-1: This is only an example to show the correct structure, your config.plist will include additional lines of existing code.
Note-2: The data values generated by
Hackingtool are base-64 encoded, if you use a Plist Editor or Clover Configurator to edit your config.plist then simply use the selected
PlatformID value in
Reverse Byte Order without the leading "
0x" for example: if you want to use the
PlatformID of
0x59120003 then ignore the leading "
0x" and split the remaining value into four, two digit bytes = 59,12,00,03 then reverse the order = 03,00,12,59 so you would enter
03001259.
Note-3: On Sandy Bridge systems the name of the Device Property will be
AAPL,snb-platform-id (not
AAPL,ig-platform-id)
Here is an example of adding the above Device Property using PlistEdit-Pro :-
View attachment 350507
Alternatively you can use Clover Configurator :-
- Open Clover Configurator and load your config.plist and select the Devices section
- Towards the bottom of page you will see two tab buttons labelled Arbitrary and Properties
- Click on the Properties button
- Click on the "+" icon under the left panel
- Copy and paste the PCI path <key> value (starts with PciRoot) from the generated patch code into the "Devices" field
- Click on the "+" icon under the right panel
- Type in "AAPL, ig-platform-id" into the "Properties Key" field
- Type in your selected "PlatformID" value into the "Properties Value" (see Note-2 below)
This is what the Device Properties look like for the the above example in Clover Configurator :-
View attachment 350108
Note-1: When using Clover Configurator we define the PCI path of the IGPU in the left panel and the name and data value of each Device Property in the right panel.
Note-2: The value for
AAPL, ig-platform-id is entered (and displayed) in
Reverse Byte Order without the leading "
0x" so for the above example of "
0x59160000" the correct value is "
00001659".
Important: All other Clover options for IGPU enabling and spoofing should be left blank/empty in the "
Devices" section of your config.plist file.
For most users injecting the correct PlatformID for "
AAPL,ig-platform-id" (and
device-id in some cases) should be all that is required and WhatEverGreen will take care of patching everything else, however on some systems it may be necessary to further modify the framebuffer defaults in oder to get all of the IGPU ports/connectors working correctly. You can use
Hackingtool to modify these more advanced settings and then generate updated patch code to add as additional Device Properties to your config.plist.
For more info on modifying the IGPU connector/port settings you should check out
CaseySJ's excellent guide which covers the topic in more detail.
Important: As detailed in
Headkaze's Guide remove
all options in the "
Graphics" section of your config.plist such as Inject Intel, ig-platform-id ... etc :-
View attachment 350109
You should also remove any DSDT edits or SSDT Hot Patches associated with the IGPU, everything else is taken care of by WhatEverGreen as long as it's one of the IGPU's listed in
post#2 of the WEG guide, support for new IGPU
PlatformID's will be added as they become available.
4K Displays
If you have a 4K display or video panel connected to the IGPU like i do on my laptop then you may need to add
-cdfon as a MacOS boot argument, this enables the pixel-clock patches that used to be handled by the CoreDisplayFixUp plug-in (now depreciated) and generally allows for higher refresh rates on high DPI display panels.
View attachment 366999
You can also add the
-cdfon argument using Clover Configurator :-
View attachment 350312
I also recommend increasing the IGPU's VRAM from the default value of 1536MB to the 2048MB maximum. Once again we can use
Hackingtool to generate the patch code for us, on the
Patch tab click on the
Advanced button and check the
VRAM 2048 MB option then click on
Generate and copy and paste the patch code for the two additional Device Properties into your config.plist ... similar to what we did above for setting AAPL,ig-platform-id :-
View attachment 366987
Note: Increasing VRAM to 2048MB on 1080P displays will have no beneficial effect.
The following screen shot of PlistEdit Pro shows the Device Properties for the HD620 IGPU on my Laptop using a frame buffer of 0x59160000 with the optional
device-id property and enabling the 2048MB VRAM patch, you can also see the raw patch code in the lower red box :-
View attachment 366997
And this is how it looks in Clover Configurator :-
View attachment 366998
Testing your Changes
Once you have made all the changes necessary to your Config.plist, save it and reboot, if you've followed the guide correctly you should now have your IGPU working. If you encounter problems check that you have installed the Kexts correctly as detailed in the
How to Install section of this Guide. Another very common mistake is that the value for the Device Property
AAPL,ig-platform-id (or
AAPL,snb-platform-id on Sandy Bridge systems) has been entered incorrectly.
Once you have completed installing and configuring WhatEverGreen, next time you run
Hackingtool it will display if the IGPU is using hardware acceleration for QE/CI and Metal Support :-
View attachment 378434
It's also advisable to check/test that WhatEverGreen has renamed the HECI device in your DSDT as IMEI and that it is active in the ioreg, run the following command in terminal :-
Terminal should report IMEI device path and the status, here is an example :-
Code:
| | +-o IMEI@16 <class IOPCIDevice, id 0x100000264, registered, matched, active, busy 0 (36 ms), retain 11>
As stated in the prerequisites section of this guide, WhatEverGreen should take care of sorting out the IMEI (Intel Management Engine Interface) , however in some very rare cases it appears that it can fail. If you get an error when performing the above test then use the Clover HECI -> IMEI Rename/Fix.
Code:
<dict>
<key>Comment</key>
<string>change HECI to IMEI</string>
<key>Disabled</key>
<false/>
<key>Find</key>
<data>
SEVDSQ==
</data>
<key>Replace</key>
<data>
SU1FSQ==
</data>
</dict>
You can also use Clover Configurator to enable the HECI -> IMEI Rename/Fix.
View attachment 382970
DRM Content - Video Playback Fails / Black Screen
WhatEverGreen includes all the code from the now depreciated "Shiki" plug-in which is responsible for enabling DRM protected content playback on Hackingtosh systems. In most instances that I've been able to test, WhetEverGreen automatically configures "Shiki" with the correct parameters based on the detected CPU/IGPU/dGPU.
Note: If you need to test if DRM Content can play on your system and you don't have any iTunes DRM video content already downloaded then you can try playing a movie trailer in iTunes (select
Films then click on a movie and select a trailer), you can test Netflix DRM by playing one of their Original Content Trailers by visiting
this page.
It's been reported by a number of users hear at TMx86 and other Forums that WhatEverGreen does not always get things right and fails to configure "Shiki" with the correct parameters which can result in a black screen when playing back DRM protected content. If you find you are unable to play DRM content in iTunes or NetFlix in a Web Browser then try adding shikigva=1 as a MacOS boot argument in your Clover config.plist.
View attachment 382439
This ensures that WhatEverGreen configures "Shiki" to use the hardware renderer of a GPU for DRM playback, the value for the shikigva= boot argument is made up by adding the following 8 BIT values together :-
001 = Force Hardware Online Renderer
002 = Allow Non BGRA
004 = Force Compatible Online Renderer
008 = Add Executable Whitelist
016 = Disabled Unused
032 = Replace Board ID
064 = Unlock FP10 Streaming
If after adding shikigva=1 (001 = Force Hardware Online Renderer) as a boot argument and re-booting you are still unable to play DRM protected content, then try changing the boot argument to shikigva=57 (001 + 008 + 016 +032) reboot your PC, and test DRM content again.
When using shikigva=1 or shikigva=57 MacOS should automatically select the most appropriate hardware renderer to use based on the detected/configured hardware, in most instances this will be the Intel IGPU and you should not need to do anything else. However if necessary you can manually configure MacOS to use a preferred GPU for DRM playback by using one of the following terminal commands :-
Force MacOS to use Intel IGPU (Default/Recommended) :-
Code:
defaults write com.apple.AppleGVA forceIntel -boolean yes
Force MacOS to use AMD/ATI dGPU :-
Code:
defaults write com.apple.AppleGVA forceATI -boolean yes
Force MacOS to use Nvidia dGPU :-
Code:
defaults write com.apple.AppleGVA forceNV -boolean yes
If after trying shikigva=1 and shikigva=57 you still cant play DRM content then you could try shikigva=60 (004 + 008 + 016 + 032) which will force MacOS to use an alternate/compatible DRM renderer method.
If necessary you can reset the MacOs DRM configuration back to defaults with the following terminal commands :-
Code:
defaults delete com.apple.coremedia
defaults delete com.apple.AppleGVA
sudo rm -rf /Users/Shared/SC\ Info
sudo defaults delete com.apple.coremedia
sudo defaults delete com.apple.AppleGVA
Once you have entered the above commands, reset your PC and try again.
I'm still trying to nail down DRM issues so if you found this section useful please post any success (or failure) stories below, so we can help others and improve the above info.
AppleALC
AppleALC is a plug-in for Lilu that dynamically patches the AppleHDA kext to enable HDA support on non-native audio codec's. Like WhatEverGreen it replaces many of the patches and kext's that we have traditionally used to enable Audio in MacOS, as such you must remove all existing AppleHDA enablers, patches, dummy kext's, DSDT Edits ... etc and ensure you have a vanilla AppleHDA kext.
HDMI Audio
AppleALC can enable HDMI audio on your DGPU (Nvidia/AMD) and/or IGPU as long as you have injected the correct Device Properties for your DGPU/IGPU (as required by WhatEverGreen), in most instances you should not need to do anything else to enable HDMI/DP audio, however in some cases it maybe necessary to change the connector type on a particular port, for more information see the section on WhatEverGreen above.
Codec Audio
First check the native name of your HDA device by opening your vanilla (without edits) DSDT in MaciASL and search for "
HDEF", if no results are found then try searching for "
HDAS" if that search fails try searching for "
AZAL"
If your HDA device is called "
HDEF" then there is no need to rename the device, however if it is called "
HDAS" then add the following Clover rename patch to the "
Clover/ACPI/Patches" section of your config.plist :-
Code:
<dict>
<key>Comment</key>
<string>change HDAS to HDEF</string>
<key>Disabled</key>
<false/>
<key>Find</key>
<data>
SERBUw==
</data>
<key>Replace</key>
<data>
SERFRg==
</data>
</dict>
If your HDA device is called "
AZAL" then the rename patch is :-
Code:
<dict>
<key>Comment</key>
<string>change AZAL to HDEF</string>
<key>Disabled</key>
<false/>
<key>Find</key>
<data>
QVpBTA==
</data>
<key>Replace</key>
<data>
SERFRg==
</data>
</dict>
You can also rename the HDA device using Clover Configurator by selecting the appropriate rename patch :-
View attachment 350284
Understanding how AppleALC works
AppleALC works a bit different to traditionally pre-patched or dummy kext AppleHDA solutions, the best way to think of AppleALC is as a large database of codec connector, layout and platform patches. Upon loading, AppleALC will automatically detect the type of codec you have and will apply a set of codec patches from its database to AppleHDA. The patch set that AppleALC will use is defined by using an index identifier. For backwards compatibility (and terminology) the patch set index identifier is the value of a property called "
layout-id" which has traditionally been used in the hackingtosh world to select a layout in a pre-patched version of AppleHDA (or dummy HDA kext).
Lilu & AppleALC interactions
When Lilu loads it finds the value of "
layout-id" and passes it to AppleALC which creates a new Device Property called "
alc-layout-id" that inherits this value. AppleALC then sets the value of "
layout-id" to a new target ID (usually 7) and patches the target layout in AppleHDA (using Lilu's patching engine) with the connector info, platform and layout files required for your codec indexed by the value of "
alc-layout-id".
This method allows AppleALC to negate the dropped layout-id's in Mojave (see the Audio section of
this post for more info ) as the injected value of "
layout-id" is only used as an index in AppleALC's codec patch database. It should be noted that AppleALC will use this layout-id re-mapping scheme on all versions of MacOS not just Mojave.
Check Supported Codecs
To see if AppleALC supports your codec look for its name in the source code's
Resources folder. If your codec is not supported then you can ask for it be included in the next version by posting on the official
AppleALC help thread. Create a post with the details of your codec (see post #1 in the help thread) ). One of the guru's there should see your post and offer to help, you will probably need to generate a codec dump in linux, I'm not going to cover that here as its out of the scope of this guide but whoever picks up your post and offers to help will give you a link on how to do this.
If your codec is already supported by AppleALC you can check which layout's are supported by opening the info.plist file within the appropriate codec folder, from the code you can see which layout id's are available, the comments may give you a clue as to which one to use,
As an example my 2017 HP Spectre X360 laptop has a ALC295 codec, so i open the info.plist within the ALC295 sub folder :-
View attachment 359220
In this example I know that Mirone's patch set is the one I need which is layout 3, in your instance read each of the comments to see if the description matches your system, if your not sure make a list of all of the available layout-id values and try each one in turn until you find one that works. You can also use HD-Patcher to see which layouts are supported (detailed below).
AppleALC Configuration
First install the latest versions of Lilu and AppleALC in to /L/E (see the
How to Install section towards the top of this guide), now all you need to do is to configure AppleALC with the layout-id you want to use, there are two methods you can use to do this.
Method 1 (Legacy Clover value)
Lilu supports querying Clover for the value of
"layout-id" from the legacy parameter "
Clover/Devices/Audio/Inject" in your config.plist so all you need to do is to set the string value of "
Inject" to the correct layout id for your codec.
Example using layout 3 :-
Code:
<key>Devices</key>
<dict>
<key>Audio</key>
<dict>
<key>AFGLowPowerState</key>
<true/>
<key>Inject</key>
<string>3</string>
<key>ResetHDA</key>
<true/>
</dict>
If you use Clover Configurator then the setting is in the
Devices Section
View attachment 350199
It should be noted that it's quite likely that Lilu will drop the legacy method of reading the value of "
layout-id" from "
Clover/Devices/Audio/Inject" at some point in the future, so you may be better of using the second method which uses Device Properties and brings AppleALC configuration in-line with other Lilu plug-in's such as WhatEverGreen.
If you don't know what Device Properties are see the "
Configuration" section of the WhatEverGreen part of this guide above.
Method-2 (Device Properties) - Recommended
After installing AppleALC + Lilu reboot and edit your config.plist and set the string value of "
Clover/Devices/Audio/Inject" to "
No" and define
"layout-id" as a custom Device Property. You can use
Hackingtool to generate the Audio Device Property code for you by clicking on the Speaker Icon on the lower tool bar, you should now see the detected Codec type and a drop down menu where you can select the layout you want to use, the drop down menu will only contain the valid layout-id's that are applicable to the detected codec.
View attachment 358912
Once you have made your selection, select the
Patch tab and uncheck everything, then check the
Audio option and then click on the
Generate Patch button.
View attachment 359183
Notice that as well as the "
layout-id" Device Property there is also an associated PCI path key.
You can now copy and paste the code from the
Hackingtool code generator straight into your config.plist making sure you keep the <dict> structure correct ... here is an example using layout-id 3 :-
Code:
<key>Devices</key>
<dict>
<key>Properties</key>
<dict>
<key>PciRoot(0x0)/Pci(0x1f,0x3)</key>
<dict>
<key>layout-id</key>
<data>
AwAAAA==
</data>
</dict>
</dict>
</dict>
Note: This is only an exmpale to show the correct structure, your config.plist will include additional lines of existing code.
Here is an example of adding layout-id 3 as a Device Property using PlistEdit-Pro :-
View attachment 360780
Alternatively you can use Clover Configurator :-
- Open Clover Configurator and load your config.plist and select the Devices section
- Towards the bottom of page you will see two tab buttons labelled Arbitrary and Properties
- Click on the Properties button
- Click on the "+" icon under the left panel
- Copy and paste the PCI path key (starts with PciRoot) from the generated code into the "Devices" field
- Click on the "+" icon under the right panel
- Type in "layout-id" into the "Properties Key" field
- Type in your "layout-id" value into the "Properties Value" field as a 8 digit Hexadecimal (eg 3 = 03000000)
This is what the above example looks like using Clover Configurator:-
View attachment 350314
Note-1: We define the audio device's PCI path key in the left panel and the Device Property in the right panel.
Note-2: The data values generated by the
Hackingtool code generator are in base-64 so if you use Clover Configurator or plist editor then you will have to convert the value to an 8 digit hex number, you can use the calculator function in
Hackingtool (Version 1.7.9+) to do this. For example you want to use layout id 13,
Hackingtool generates a base64 value of "DQAAAA==" if we enter this in to
Hackingtool's calculator we get a hex value of "0d 00 00 00" enter this as the value for "
layout-id" without the spaces.
View attachment 383022
After making the changes/edits save your config.plist and reboot, now you can test if the audio working. If audio is not working then work through each of the valid layout-id's for your codec, saving the config.plist file and rebooting between each test.
If after testing all valid values of layout-id for your codec audio is still not working then you may have a codec configuration that needs a new patch set ... as with a non-supported codec, the best place to get help is the official
AppleALC help thread. Create a post with the details of your codec (see post #1 in the help thread) ) and write that none of the existing layouts work on your system. One of the AppleHDA guru's should see your post and offer to help.
Checking if AppleALC has loaded Correctly
We can easily check if AppleALC has loaded and initialised correctly by using IORegisteryExplorer, if you don't already have this installed you can download it using this
link.
Run IORegisteryExplorer and enter "
HDEF" in the search box, you should now see the ioreg directory tree for your "
HDEF" device, using the above example this is what mine looks like :-
View attachment 350275
We can see that AppleALC has automatically created a new property called "
alc-layout-id" which has inherited the layout-id value of 3 as defined in the config.plist (using Clover/Devices/Audio/Inject or as a Device Property) ... remember that this is the index value to the patch set in the AppleALC patch database. We can also see that "
layout-id" has now been set to 7 which is the target layout in AppleHDA that AppleALC has patched and that MacOS is using.
If you don't see "
alc-layout-id" in your "
HDEF" directory tree then AppleALC is not loading or initialising correctly, the usual cause of this is that the kexts have not been installed correctly. Try deleting the Lilu + AppleALC kext's from /L/E, download them again and re-install using the method detailed in the
How to Install section of this guide.
HPET Issues (High Precision Event Timer)
After following the guide to install AppleALC and performing the above check you find that the "
alc-layout-id" property exists in the ioreg and the value for it and the property "
layout-id" seem correct but you still have no sound then its possible that you might be suffering form an IRQ Conflict caused by the HPET (High Precision Event Timer).
The HPET is a basic requirement for MacOS to run correctly and almost all install guides on this forum state that you should enable the HPET option in your BIOS, however on some motherboards and laptops the native DSDT code for the HPET can cause a IQR conflict that can stop the AppleHDA kext initialising correctly.
One method of checking for this issue (suggested by @
buzzvicky) is by executing the following command in terminal :-
Code:
kextstat | grep 'Lilu\|AppleALC\|AppleHDA'
In the resulting output you should see the Lilu, AppleALC & AppleHDA kexts listed ...
Code:
MonkeyPro-2018:~ Jay$ kextstat | grep 'Lilu\|AppleALC\|AppleHDA'
20 4 0xffffff7f81041000 0x22000 0x22000 as.vit9696.Lilu (1.2.8) 54014689-C8DA-318B-84F4-944BBA7AD2AC <8 6 5 3 2 1>
23 0 0xffffff7f811bd000 0xdf000 0xdf000 as.vit9696.AppleALC (1.3.3) B60FCBAF-6BC2-36EF-A1E6-D5BE2863C35B <20 13 8 6 5 3 2 1>
138 1 0xffffff7f830a7000 0x1d000 0x1d000 com.apple.driver.AppleHDAController (282.10) 70256EC9-AF38-31BD-A3C5-9C0E30B64AA3 <137 113 107 13 8 7 6 5 3 1>
157 0 0xffffff7f8323a000 0xb7000 0xb7000 com.apple.driver.AppleHDA (282.10) B2208DA8-8CD9-36D8-BD59-C6D9A5379585 <156 138 137 124 113 107 7 6 5 3 1>
159 0 0xffffff7f830c6000 0x2000 0x2000 com.apple.driver.AppleHDAHardwareConfigDriver (282.10) C4F674A0-5828-3D97-82BF-A81C8B8BDDBA <5 3>
As you can see from the above example if
AppleHDA is loading then you will also see the AppleHDAController and AppleHDAHardwareConfigDriver kexts but the important one to note is
AppleHDA.
If you do not see
AppleHDA in the output (
com.apple.driver.AppleHDA) then first check your BIOS settings and ensure that you have the HPET option enabled, if it is enabled and you still do not see
AppleHDA in the output from the above command then you'll need to patch the HPET code in your DSDT.
The simplest method is to use the Cover option
FixHPET in ACPI/DSDT/Fixes :-
Code:
<key>ACPI</key>
<dict>
<key>DSDT</key>
<dict>
<key>Fixes</key>
<dict>
<key>FixHPET</key>
<true/>
You can also enable the option using Clover Configurator :-
View attachment 375289
This should work for most users however if after applying the Clover HPET fix you still find that AppleHDA is not loading (using the above terminal command) then you may need to apply the fix directly to your DSDT, RehabMan has a
DSDT patch in his Repo which you can apply to your DSDT using MaciASL:-
Code:
#Maintained by: RehabMan
# HPET fix to avoid AppleIntelCPUPowerManagement panic
into method label _STA parent_hid PNP0103 remove_entry;
into device name_hid PNP0103 code_regex Name\s\(_STA\,\s+0x0F\) remove_matched;
into device name_hid PNP0103 insert
begin
Name (_STA, 0x0F)\n
end;
into method label _CRS parent_hid PNP0103 remove_entry;
into device name_hid PNP0103 insert
begin
Method (_CRS, 0, NotSerialized)\n
{\n
Return (BUF0)\n
}\n
end;
To apply the patch open your DSDT in MaciASL, click on the
Patch button and copy/paste the above code into the patch editor and then click on
Apply, save the patched DSDT and try again, for more info on patching your DSDT see
Rehabmans full guide.
AppleALC EAPD wake verbs
As an added bonus, AppleALC also takes care of EAPD wake verbs for most codec's so there is no need to install/use Codec Commander, you can check if AppleALC supports EAPD wake verbs for your codec by looking at the
release history commit comments, if it is supported and you already have Codec Commander installed then you should remove it .
AirportBrcmFixup
This plug-in is pretty straight forward, it includes a set of patches required for native and non-native Broadcom Airport/Wi-Fi cards. The patches deal with things like enabling continuity and handoff, renaming your WiFi as an Airport device, plus a few other handy patches. As with all the other Lilu plug-in's in most cases (see notes below) you should remove all previous WiFi related patches and enabler kext's.
One reason to consider using this plug-in is that it negates the problem that you can no longer use a Clover patch to enable Handoff on MacOS 10.13.X and 10.14.X. You don't need to set any Device Properties for this plug-in, if it finds a supported WiFi device it will apply all the necessary patches automatically.
If you don't already know the VID & PID of your installed WiFi adapter then you can use DPCIManager which you can download using this
link. Once downloaded simply extract and run DPCIManager and click on the "
PCI List" tab, find your WiFi device in the list and make a note of the Vendor ID (VID) and PCI Device ID (PID).
View attachment 360643
In the above example my WiFi device has a VID of 14E4 (Broadcom) and a PID of 43BA (BCM43602 Chipset)
To see if your WiFi device is supported, take a look at the
info.plist on the projects Git-Hub project page and search for your WiFi Devices PID.
View attachment 360645
If you see your devices VID + PID in the list then your good to go, simply install AirportBrcmFixup (and Lilu if not already installed) using the method detailed in the
How to Install section of this guide.
If necessary, you can over-ride the default MacOS WiFi local and explicitly set a country code for your WiFi device using the boot argument
brcmfx-country=XX, this is sometimes necessary to get 5Ghz WiFi working at full speed on some WiFi routers. A common value for this is "#a" which is a special value that effectively tells MacOS to ignore the WiFi country code set by your router. I've always had to use the "#a" country code on all versions of MacOS in order to get full 5Ghz WiFi bandwidth with my router.
View attachment 350313
Note 1: I think the
guide/readme.md on this plug-in's Git-Hub page is a bit out of date in that states it should be used with other 3rd party WiFi enablers. I believe that earlier versions of AirportBrcmFixup did require the use of additional software depending on what type of card you have. However from my testing it appears that this is no longer the case and AirportBrcmFixup should do pretty much everything required so no need for any other software.
Note 2: AirportBrcmFixup only deals with the Airport/WiFi side of a combo card it does nothing to enable/support Bluetooth. To enable Bluetooth on all my Hackingtosh systems I use RehabMans BrcmPatchRAM ... see his
Git-Hub Project page for more info.
I've tested AirportBrcmFixup with a DW1830 (BCM43602) in my laptop and a BCM943602CS in my desktop system and it works great, no other patches or enablers needed. .. handoff and continuity have never worked better.
Based on my experience I suggest you try AirportBrcmFixup on it's own and remove all other WiFi/Airport enablers, kext's and patches ... as long as your device is supported (see the
info.plsit) you should be ok, if it does not work then you may need to add one of the 3rd party kext enablers mentioned in the
readme.md .... please post your success (and failures) below so we can confirm this for other users.
For a full list of all the patches this plug-in provides along with a list of boot arguments see the projects Git-Hub
readme.md.
Other useful Lilu Plug-in's
BT4LEContiunityFixup
If after installing AirportBrcmFixup you continue to have BT Continuity issues (AirDrop, Handoff, FaceTime Continuity .. etc) you could try installing
BT4LEContinuityFixup which applies a few more specific patches to enable MacOS BT-LE Continuity features on non-native Broadcom BT-LE chipsets ... as with the other Lilu plug-in's you should disable or remove any existing Clover Bluetooth patches, but be sure to keep the BrcmPatchRAM kexts in /L/E.
AppleBacklightFixup
A Lilu alternative to ReHabMan's AppleBacklightInjector.kext and clover patch,
AppleBacklightFixup should work on all versions of OSX, it still requires the hot patch SSDT-PNLF.aml see
ReHabMans guide for full details. I've used it on my 2017 HP Spectre X360 laptop with great success.
HibernationFixup
As the name suggest this Lilu plug-in allows the enabling of MacOS save-to-disk hibernation modes 3 and 25 on certain systems. I have not used
HibernationFixup myself but have read many positive posts that it does work as long as your system meets the hardware requirements (specifically native NVRAM, not emulated). Be sure to read all the documentation first before installing.
VirtualSMC
A lilu plugin that emulates the Apple SMC (System Management Controller) .. typically we have always used FakeSMC for this task and as of now (January 2019) I would recommend that you continue to use FakeSMC as its still unstable on some systems and needs more sensor plugins before it can be recommended over FakeSMC.
I'm sure that
VirtualSMC will at some point surpass FakeSMC but it is still quite early in its development cycle. I think this is a plug-in to keep an eye on as I am sure at some point in the future it will be preferable to use
VirtualSMC in place of FakeSMC.
Final thoughts
Lilu and its plug-in's such as WhatEverGreen, AppleALC and AirportBrcmFixup
consolidates everything that has been learnt by the
entire hackingtosh community over the last five years and does a lot of the hard work that used to achieved with multiple Clover patches, custom and dummy kext's, hot patches ... etc with just a handful of kext's and the injection of a few Device Properties.
Once you take the time to understand Lilu and its plug-in's you will find that they really can simplify the patching of critical area's of MacOS with the minimum amount of effort. Of course there are always going to be exceptions where these solutions wont work but for many users, Lilu and its plug-in's should be considered a viable and mature alternative to the traditional hackingtosh methods that we have used for the last few years.
It goes without saying that Lilu and its plug-in's are in constant development so I recommend keeping an eye on the Git-Hub release pages, the latest version of each project will always be shown at the top of the page along with details of the changes and commits to that version.
I'd like to take this opportunity to thank all of the developers involved with Lilu and its plug-in's for all their hard work and their contribution to the hackingtosh community, it should be noted that they in-turn (where applicable) acknowledge the original creators of any methods that some of the plug-in's use, these credits can be seen at the bottom of the readme.md on each of the Git-Hub project pages.
Cheers
Jay
Getting further Help and Support
If you need help outside the basic scope of this guide then do not post your question here, please create a new thread in the appropriate sub section of the forums such as
Post Install,
Laptops .. etc.
If you suspect there is a bug in Lilu or one of it's plug-in's then you should post your findings to the relevant support thread(s) documented in the readme.md of the appropriate Git-Hub project page, the same is true if you need to report an unsupported device for inclusion in the next release.
, I'm going to study the howto of