Go to page

Go to page

Moderator

In order to make many OS X features work well on a laptop, you will always need a properly patched DSDT (and maybe some of the SSDTs). The purpose of this guide is to provide a foundation for proper patching of your OEM DSDT/SSDTs.

Although you may be tempted to use a DSDT from another computer, it will almost always end in failure. You simply cannot be certain it is valid to use ACPI files from another computer. Even minor differences in hardware configuration (BIOS version, amount of memory installed, BIOS options selected, and other hardware differences such as which WiFi card is installed) can make for differences that cause instability and weird bugs if you use foreign ACPI files. Such differences can make various OperationRegion addresses different, which makes a patched DSDT for one system incompatible with another. It is also not uncommon for the same laptop model to be produced in different runs with different motherboards, and potentially incompatible ACPI files.

Keep in mind that even changes you make to your own system (BIOS, hardware, etc.) will require re-extract, re-patch.

If any of the following is changed, you must re-extract, re-patch, as these changes may cause significant changes to the native ACPI (especially SystemMemory regions):
- updating BIOS
- changing any BIOS option
- changing hardware or memory configuration

All BIOS implementations provide ACPI files to the OS. So, on any OS, you can extract them for patching later. Extraction can therefore be done on Linux, OS X, Windows, or even in the Clover bootloader. Native files extracted are generally identical, although because of the software used to extract, they may be named differently.

This guide will focus on three methods of extraction: using F4 with Clover, using patchmatic in OS X, or using Linux.
Only the first is the recommended method. The others are provided for your information only.

Extracting with Clover F4 (recommended):

Extracting with Clover F4 is recommended, due to ease of extraction, and due to ease of comparison between ACPI/origin and ACPI/patched (for troubleshooting).

At the main Clover bootloader screen, you can press F4 and Clover will dump the native ACPI files to EFI/Clover/ACPI/origin. You can then access them after you boot OS X to disassemble them and patch. Note that some BIOS implementations reverse the function of Fn+F4 with F4, so when in doubt, press both Fn+F4 and F4. There is no feedback during or after the dump, just a slight delay as the files are written. The delay is more noticeable if they are being written to USB, as would be the case when booting from a Clover USB.

Sometimes, Clover F4 will write duplicate SSDTs. These duplicates will cause problems during disassembly. If you run into issues (duplicate definitions) during disassembly, you will need to analyse all SSDTs to eliminate the files which are duplicate. It is easy to see which are duplicates by looking at the file sizes. Files with equal size are likely duplicates.

You can see file sizes in bytes of all SSDTs in Terminal:

Code:

ls -l SSDT*.aml

Extracting with 'patchmatic' (NOT recommended):

If you've already installed OS X, provided you're not currently booting with any patched ACPI files, you can extract your native DSDT/SSDT with patchmatic. Download the patchmatic binary here: https://github.com/RehabMan/OS-X-MaciASL-patchmatic (be sure to read the README as the download location is linked from it). For ease of use in Terminal, you should copy the binary (inside the ZIP) to /usr/bin.

After installing patchmatic, you can invoke it in Terminal, as such:

Code:

cd ~/Desktop
mkdir extract
cd extract
patchmatic -extract

The patchmatic binary will extract all loaded ACPI files and place them in the current directory. If you're using any options in the bootloader that affect the injected DSDT/SSDT, you will not get native ACPI files, so be sure you're not using those options. For example, if you're using (Chameleon) DropSSDT=Yes, or (Clover) DropOem=true, the native SSDTs are being dropped before OS X can load them, so you'll be missing them in the patchmatic output. Same goes for any Clover DSDT "Fixes" -- those fixes are patching the native DSDT, and to do your own DSDT patching, you don't want that. Options such as GeneratePStates/GenerateCStates=Yes, or with Clover /ACPI/SSDT/Generate/CStates /ACPI/SSDT/Generate/PStates will inject extra SSDTs which can cause complications with disassembly.

It is for all those reasons, it is often easier to extract via Linux or using Clover F4.

Note: Using 'patchmatic -extract' to confirm you're patching DSDT/SSDTs as you expect is a useful diagnostic tool.

Extracting with Linux (NOT recommended):

In Linux, the native ACPI files are available directly from the file system. You can find them at /sys/firmware/acpi/tables and /sys/firmware/acpi/tables/dynamic. It is possible to copy the entire set with a single command in Terminal.

You should copy the files to a FAT32 formatted USB. Using FAT32 avoids permissions issues as FAT32 has no file permissions. The value of DEST for an auto-mounted USB will depend on the version of Linux you're using and how you booted it. You can see the mount-point by typing 'mount' in Terminal, or hover your mouse over the volume name in the Linux file explorer.

Preparing tools for disassembly

To properly disassemble your extracted files, you need the iasl compiler, which is run from Terminal.

You will need a recent build of iasl to disassemble them properly. There is an appropriate version available here: https://bitbucket.org/RehabMan/acpica/downloads/. It is a good idea to copy the iasl binary to your path (eg. /usr/bin), so it is easily accessed from Terminal.

For example, if you downloaded it to ~/Downloads/iasl.zip, you can extract and copy it in Terminal:

Code:

cd ~/Downloads
unzip iasl.zip
sudo cp iasl /usr/bin

Building the latest iasl from github

You can also build the latest version of my iasl from my github. The newer version of iasl will eventually be available at the bitbucket link, but for those who want to be on the "bleeding edge", you can build it yourself. The latest version always tends to have experimental and not well tested code.

And assuming you have MaciASL.app installed to /Applications, you can use the new version (that you just built and installed to /usr/bin) in MaciASL as well:

Code:

sudo cp /usr/bin/iasl /Applications/MaciASL.app/Contents/MacOS/iasl62

Disassembling ACPI files

Although the extracted native files can be opened directly in MaciASL, it is not recommended. Opening an AML file directly in MaciASL will cause MaciASL to disassemble the file (with iasl) standalone, and if the AML has complex references to other AMLs, it will not disassemble it correctly. You'll be left with many hard to fix errors.

As a result, it is better to disassemble all files as a group using iasl in Terminal. To prepare, place all DSDT and SSDT files in a single directory (DO NOT copy ACPI files that don't begin with DSDT or SSDT), and change the names such that they have an .aml extension.

Note: Do NOT attempt to disassemble other ACPI files with the -da option. It will not work.

Note: Also read the section below regarding refs.txt. Using refs.txt takes little more effort, but can eliminate many common errors.

From this point onward, you will work exclusively with the resulting *.dsl files using MaciASL. Of course, to use them you must save as "ACPI Machine Language Binary" with an extension .aml and place them where they will be loaded by the bootloader. But keep your patched .dsl files in case you need to apply more patches in the future.

Let me state it quite simply (because this comes up a lot): If you are opening an AML file directly in MaciASL and clicking Compile, you are doing it WRONG. Let that soak into the gray matter between your ears for a minute. The only exception to this rule is AML files compiled with a recent enough iasl that places embedded External opcodes in the file. This includes files you compiled yourself with the current iasl and native ACPI compiled by the OEM (generally, Skylake and later).

Note: The new tools with ACPI 6.1 (and later) are much more robust when dealing with AML files that have been compiled with the new version of iasl. ACPI 6.1+ adds a feature to the compiler where opcodes for External references are added to the AML binary. ACPI interpreters ignore this data, but the data is useful to the disassembler (also only ACPI 6.1+ iasl) to create a better disassembly from a standalone AML. As a result, you might find that AML files that have been recompiled with the latest tools may open directly more reliably. Of course, existing OEM ACPI DSDT and SSDTs are not using the new tools at this point, so you still must disassemble initially with all DSDT/SSDT with option -da, as described in this guide.

Note regarding Snow Leopard ACPI implementation: Unfortunately, the 10.6.8 ACPI is old enough that it chokes on AMLs with the external opcode. If you are planning to use your ACPI files with Snow Leopard use the undocumented "-oe" switch to iasl when you compile your AML files. This option is not set when you compile (Save As) from MaciASL, so you will need to compile your files in Terminal. The "-oe" option disables generation of the external opcode in the output AML files.

Disassembly with refs.txt

Sometimes there are additional unresolved externals (symbols not defined in any file). The iasl disassembler will attempt to guess the number of arguments, but often it guesses poorly. You can correct it, by providing the External declarations in a text file. Some common unresolved symbols are SGPO, ECRD, ECWT, and MMTB.

The following refs.txt content has some common (and not so common) missing symbols (as reported by users in this thread) that the disassembler tends to be confused by.

First create refs.txt in the directory where your DSDT/SSDT files are:

Note: With newer ACPI sets (generally Skylake and later), the ACPI files have been compiled with a new enough version of iasl that embeds External opcodes in the resulting AML code. For these newer ACPI sets, no need for -da and especially not refs.txt as the refs.txt content here may conflict with the embedded External opcodes.

A handy way to create refs.txt is to use pbpaste in Terminal. Copy the text above to the clipboard (I'm assuming you know how to do that), then:

Code:

pbpaste>refs.txt

That will create refs.txt in your current working directory.

Then use it during disassembly:

Code:

iasl -da -dl -fe refs.txt DSDT.aml SSDT*.aml

Analyzing native ACPI

After disassembly, you may want to look at the content of each .dsl file to familiarize yourself with the content in each. Certain patching is dependent on the content. For example, if you're patching to disable the discrete graphics device, you may be looking for the _OFF method as it relates to that device (this process is covered in a separate guide, linked later in this guide).

Even by disassembling all at once (iasl with -da option), the native files can still have errors. The disassembled files have errors due to changes in iasl over time, imperfections in iasl itself, and differences in the compilation environment between our laptops and the OEM. A common cause of errors (my theory), for example, is that some of the methods referenced are actually inside Windows (MMTB and MDBG for example). There is also clearly cases where bugs are in the code or code was written uninitentionally (sometimes hard to tell the difference).

So.. after determining which files you need, you must patch them so they compile without errors. There are many common patches for such errors in my laptop patch repository for MaciASL.

Note: I do not test my patches with DSDT Editor. It has too many bugs and a very old version of iasl. Please do not ask me about it.

Be certain to always read the README, in order to download from the correct location and in order to setup MaciASL correctly. The patches for syntax/error problems begin with "[syn]" in the name. Common examples for older DSDTs are "Fix _PLD Buffer/Package Error", "Fix TNOT Error", and "Fix FPED Parse Error". In order to determine which patch you need, you can look at the error message coming from the iasl compiler and the code at the line the error was detected. You can also attempt to apply a patch just to see if it makes changes as shown in the Preview window in MaciASL. If you're not familiar with each type of error, it can take some experimentation and trial/error.

For some errors, you can simply remove the line of code causing the error. But, it depends on whether the line is necessary for proper operation of the code or not. For example, errors caused by 'External' declarations can generally be removed to fix the error. If you wish, you can create automated patches of your own to remove these lines.

It helps to have some experience with the ACPI spec and some programming experience.

Your goal is to get each .dsl file to compile without errors (warnings/remarks/optimizations are ok). Once you have files that compile without errors, you can move on to patching them to fix issues you may have with your OS X installation.

It is very common to have extraneous/unnecessary External declarations. For example a recent DSDT I looked at had quite a few "Name already exists in scope" errors. For DTSE, DTS1, DTS2, DTS4, BNUM, PDTS, PKGA, SPST.

The fix is to simply comment out the related External declarations.
For example:

Another common error in recent DSDT is with ECRW (in a _CRS method). It is a very common error caused by an iasl bug. I'm not going to add a MaciASL patch for it, since it will eventually be fixed by Intel (it is a regression).

Generally, a DSDT patch should only be applied after finding a need for that specific fix. But there are several patches that are commonly needed and that have only a small chance of causing a problem. They are in my laptop repo and are listed here:
"Fix _WAK Arg0 v2"
"HPET Fix"
"SMBUS Fix"
"IRQ Fix"
"RTC Fix"
"OS Check Fix"
"Fix Mutex with non-zero SyncLevel"
"Fix PNOT/PPNT" (use only if you're dropping CPU related SSDTs)
"Add IMEI" (do not use if your DSDT or SSDTs already have IMEI/HECI/MEI device)

Note: The OS Check Fix patch you use has nothing to do with the version of Windows the laptop came with, nor with the version of Windows you're currently using.

Note: Do not use the "Fix PNOT/PPNT" patch if you're including all OEM SSDTs. It is intended only for the case you omit the OEM CPU related SSDTs.

These patches can be used to inject power properties for USB:
"6-series USB"
"7-series/8-series USB"

The _PRW patches can be used to fix "instant wake" where the laptop will not sleep without waking up seconds after sleep begins. Use only "USB _PRW 0x6D (instant wake)" or "USB _PRW 0x0D (instant wake)" as it relates to existing code in your DSDT (also note specific versions of these patches for Skylake and later). You should examine your DSDT to determine what the relevant _PRW methods return to be certain the patch is appropriate for your DSDT.

If you have a Haswell CPU/8-series chipset, and AppleLPC.kext is not loading, you should use this patch to inject a compatible ID that will allow it to load:
"Haswell LPC"

If you have a Skylake CPU/100-series chipset, and AppleLPC.kext is not loading, you should use this patch to inject a compatible ID that will allow it to load:
"Skylake LPC"
Note: AppleLPC not likely needed with Skylake and later.

Note regarding renames: Renames must be "balanced." It is common to rename objects to better match what OS X expects (example "Rename GFX0 to IGPU" for proper IGPU power management). In such cases, all DSDT/SSDTs with references to that name must also be renamed. This is why renames are best accomplished with config.plist/ACPI/DSDT/Patches.

Note regarding duplicate identifiers: You must be sure that your patched files do not contain duplicate identifiers. A common case would be adding a _DSM method to a given path in one SSDT, where the OEM has defined a _DSM at the same path in another SSDT. To avoid this problem, you can use the "Remove _DSM methods" patch as one of the first patches you do to all DSDT/SSDTs. Also, "Rename _DSM methods to XDSM" is an alternative (sometimes "Remove _DSM methods" exposes a bug in MaciASL).

When following a guide for a specific laptop, it may instruct you to apply a patch that is provided in the post itself. You will recognize it as the syntax used will look similar to other patches you've seen in the repository (eg. 'into_all method label FOO code_regex xxyy removeall_matched;'). These patches are intended to be pasted directly into the patch window in MaciASL so they can be applied.

Note: In many cases, DSDT patches are used in conjunction with additional kexts, patched kexts, or Clover config.plist patches that patch the system kexts as they are loaded.

Patches for using patched AppleHDA

With patched AppleHDA, there are two patches that are needed in conjunction with the kext:
"Audio Layout 12" (change the layout-id from 12 to the one used by your DSDT)
"IRQ Fix"

Note that you must have an AppleHDA that matches your codec, and must determine which layout-id was chosen. The layout-id is an arbitrary choice by the creator of the patched AppleHDA.

To determine the layout-id used by a particular patched AppleHDA: First you need to know your codec id in decimal (eg. 0x10ec0269 = 283902569). Then look in the Info.plist for AppleHDAHardwareConfigDriver.kext (at AppleHDA.kext/Contents/PlugIns/AppleHDAHardwareConfigDriver.kext/Contents/Info.plist), find your codec id under HDAConfigDefault (there may be many entries in a sloppy patched AppleHDA or only one). The LayoutID that matches your codec id is the layout id you need. It is possible that a patched AppleHDA contains more than one layout-id for a given codec. In that case, choose the one you want to use.

Saving files for loading by the bootloader

In order to use your patched DSDT/SSDTs, you must save them where the bootloader can load them. Each bootloader location is unique and has different requirements for naming. Files must be saved in "ACPI Machine Language Binary" (MaciASL->Save As). Saving a text file (dsl) with an AML extension will likely cause panic or very strange behavior in OS X.

Clover: Files should be placed on the Clover bootloader partition (usually the EFI partition), in EFI/Clover/ACPI/patched. DSDT.aml, if present, will automatically replace the OEM DSDT. This guide (and other guides linked from this guide) assumes you are using config.plist/ACPI/AutoMerge=true, config.plist/ACPI/SSDT/DropOem=false. With AutoMerge=true, patched SSDTs can be placed in ACPI/patched with their original name (from ACPI/origin) and they will be inserted such that the original order of SSDTs is not disturbed. It is not necessary (or advised) to use SortedOrder with AutoMerge=true. Other configurations are covered below in "Recommended configurations".

As mentioned above, a new feature in the RehabMan fork of Clover allows you to replace OEM SSDTs without using DropOem=true, and without using SortedOrder, all the while maintaining original order of the unpatched and patched SSDTs as injected by Clover. By setting config.plist/ACPI/AutoMerge=true, this feature is enabled. The SSDT must retain its original numbering scheme when placed in ACPI/patched. This feature is fully working as of 2017-12-15, Clover_v2.4k_r4359.RM-4506.c5fc0346.zip, on the RehabMan bitbucket site. The required changes are implemented in the official Clover (on sourceforge) as of r4334 (but there are bugs you may run into, use the RehabMan build). Each of the plists linked by the main laptop guide uses AutoMerge=true by default.

Although you can use patched DSDT and patched SSDTs in Chameleon, this guide will not cover it. Chameleon is not recommended. Use Clover instead.

Full patched DSDT + SSDTs:
- patched DSDT.aml in ACPI/patched
- full set of static patched OEM SSDTs in ACPI/patched (original names as from ACPI/origin)
- add-on SSDTs also placed in ACPI/patched
- renames in config.plist not recommended (they will apply only to DSDT.aml)
- SortedOrder required to set SSDT load order
- DropOem=true

Floating regions

In ACPI, an OperationRegion can define a MMIO region, SystemMemory region, EmbeddedControl region, etc. These regions usually have fixed addresses dependent only on the machine configuration, BIOS version, or BIOS options. Sometimes, these regions can change randomly or unexpectedly. This is referred to as "floating regions".

Since by patching DSDT and/or SSDTs, we are providing a snapshot of these addresses at a given point in time, they may not match up should the BIOS decide to place such regions at a different address. If this is the case, you may notice that certain features are intermittently working, or other stability issues that appear to be random.

If you have randomly floating regions, you can try Clover's FixRegions feature (config.plist/ACPI/DSDT/Fixes/FixRegions=true). You can find the details in the Clover Wiki. Note: Only floating regions in DSDT can be fixed by FixRegions. Floating regions in SSDTs are problematic and there is no good solution other than to not provide patched SSDTs for SSDTs subject to randomly floating regions. Working around floating regions in patched SSDTs is beyond the scope of this guide. Note that FixRegions is relatively buggy. It cannot fix all regions and it can sometimes "fix" regions incorrectly.

Do not treat this thread as your private troubleshooting thread. If you have a specific problem with your specific laptop, open a separate thread. If you see something here that is in error, or wish to make a contribution, please reply to this thread.

Problem Reporting

Please read above "Providing Feedback". It is best to open a separate thread.

In that separate thread, describe you problem clearly. And provide relevant data...

And here is my MaciASL patch source. Because I haven't enough knowledge, so I just can make some simple patch. And I think you can modify part of them better. Then add to your patch source.

For example, in my patch: syntax/SSDT_P8XH_Error_Fix.txt, it generally appears in some ivy bridge Asus laptops's SSDT. I made this patch to fix this error, but I'm not sure this is a correct way to fix it. If you can make a better patch, that will be wonderful.https://github.com/Yuki-Judai/dxxs-DSDT-Patch

And here is my MaciASL patch source. Because I haven't enough knowledge, so I just can make some simple patch. And I think you can modify part of them better. Then add to your patch source.

For example, in my patch: syntax/SSDT_P8XH_Error_Fix.txt, it generally appears in some ivy bridge Asus laptops's SSDT. I made this patch to fix this error, but I'm not sure this is a correct way to fix it. If you can make a better patch, that will be wonderful.https://github.com/Yuki-Judai/dxxs-DSDT-Patch

It is because you have generated SSDTs from the bootloader in your set (eg. from GeneratePStates=Yes GenerateCStates=Yes). Since they are not part of the OEM set, you need to eliminate them (SSDT-4.aml, SSDT-5.aml), or use a different extraction method (eg. Linux or Clover F4).