- Joined
- Jul 22, 2018
- Messages
- 8,457
- Motherboard
- Supermicro X11SPA-T
- CPU
- Intel Xeon W-3275 28 Core
- Graphics
- 2xAMD RX 580 8GB
- OS X/macOS
- 13.x
- Bootloader
- OpenCore (UEFI)
- Mac
- Mac mini
- MacBook Pro
- Mobile Phone
- Android
- iOS
How to Patch APIC for macOS [Clover/OpenCore]
This guide describes how to patch APIC for macOS. This guide is supported by both, i.e Clover and OpenCore Bootloader. By following this guide, you'll be able to patch the APIC Table for booting macOS.
Overview
APIC stands for Advanced Programmable Interrupt Controller. Its parameters are defined in the MADT (Multiple APIC Description Table). If this table is missing the "NMI" section, the system can only boot by setting the kernel parameter cpus=1 or with a patched kernel (Lapic NMI).
On a few systems, some HEDT users may experience a Kernel Panic when booting into macOS, before reaching the installation stage. Although there could be several underlying causes for a Kernel Panic, the panic is related to more cores defined in the APIC Table than actually present. This can also be seen using the verbose mode:
This is because macOS assumes that the first CPU in ACPI is always enabled, which may not always be true for HEDT and Server grade Systems. To fix this issue, you'll need to patch the APIC Table and thereafter, you can boot into macOS. This is mainly relevant for HEDT Systems like X58, X79, X99, and X299 but might be helpful for other systems with higher CPU Core Count.
Initially, to get around this APIC issue, a workaround was introduced in Clover called
The steps mentioned below are only valid if your system has a Kernel Panic relating to the CPU Core count and will not work if your system has a Kernel Panic due to some other cause. Please check the verbose log to ensure you're in the right direction.
Requirements
Following are the requirements for patching APIC Table on macOS. Please ensure you meet the requirements before proceeding with this guide.
Assumptions:
This guide assumes that you have already some experience with the following. Having some of the following experience can be really helpful when following the guide.
- macOS/OS X Bootable USB with a properly configured EFI
- Basic config.plist editing skills
- Basic MaciASL usage
- Basic Clover/OpenCore knowledge
- Basic knowledge of installing/injecting kexts
Method #1: Using Clover HotPatch
Using Clover Hotpatches, you can patch the APIC Table on the fly. However, this method is limited to Clover bootloader only as OpenCore does not have an equivalent of the PatchAPIC option. To patch the APIC Table using Clover's Hotpatch method, follow the steps below.
1. Mount your ESP
2. Open your
3. Enable the
4. Save your
5. Restart your system for the applied changes to take effect. It is recommended to reset NVRAM twice at least.
Method #2: Using Manual SSDT Patch
Using Clover, APIC can be patched using one single click, on the fly. However, with the introduction of OpenCore, where a majority of ACPI Fixes don't exist unlike Clover, you'll have to patch the APIC Table manually. Although this method is supported by both i.e Clover and OpenCore Bootloader, beginner users may find this method a bit difficult. To patch APIC using the "Manual SSDT Patch", follow the steps below.
STEP 1: Extracting ACPI Tables
The very first step is to extract your native ACPI Tables. We recommend it extracting using Clover, for the highest level of integrity. If you're not aware of how to do that, a guide is already available which is linked below.
elitemacx86.com
STEP 2: Analyzing the Native APIC Table
Now, we would need to take a look at our native APIC Table. This is required because by examining the APIC Table, we can get to know whether the APIC Table needs to be patched or not and specifically what areas to patch.
Upon taking a look at our native APIC Table:
Here we can see a list of all the CPU threads and info about each one of them. Let's look at the first
Here we have some important info, but the most important part is the
Open your DSDT using MaciASL and search for
If you take a look carefully, here we've some important info regarding the first CPU:
If we check the ACPI Spec, section 19.6.108, we see the info is parsed as follows:
Now if we look at the
STEP 3: Checking for Compiling Errors
Before you start patching the APIC Table to fix the Kernel Panic, you should try to compile the APIC Table and look for any possible errors, like in our case. This is because prior to patching the APIC Table, the native APIC Table can have errors due to several underlying factors such as changes in iasl, bugs in iasl, differences in the compilation environments between our system and the OEM, and sometimes the Table itself and continuing to patch them will cause errors when compiling. These errors must be fixed prior to patching otherwise even after patching the APIC Table, it will not be compiled and saved further, and determining whether the specific patch/changes are causing the errors or the native APIC Table itself can be difficult.
Most of these errors can be fixed manually. In order to determine the error, you can simply 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.
A few errors can be fixed by removing/uncommenting the lines causing the error. However, it depends on whether the line is necessary for the proper operation of the code or not. For example, errors caused by External declarations can be generally removed to fix the error. Please note that each APIC Table can differ from system to system and can have different errors than described in this guide. However, as mentioned above, you must fix such errors so that the Table can compile without errors. If you have any experience with the ACPI spec and some programming experience, it can be really helpful. The goal is to get the native APIC Table to compile without any errors. Once you have the APIC Table that compiles without errors, you can start patching your APIC Table to fix the Kernel Panic.
For a few systems, it can be common to have
Let's take an example of our SSDT to check for compiling errors.
1. Open the native APIC Table and click on Compile and look for errors in the Compiler Summary. If there's an error, fix it and again click on Compile. If there are no errors, you can simply skip this step and continue with STEP #4.
In our case when compiling the native APIC Table, it has an Unknown subtable type (MADT) error due to which the SSDT cannot be compiled and therefore needs to be fixed.
Upon checking the line causing errors, we can see the root cause.
2. To fix the issue, we just need to remove the entire Unknown Subtable Type which is causing the issue. In our case, the Unknown Subtable Type line starts from 454 and ends at line 619.
3. Click on Compile and look for errors in the Compiler Summary. If the error persists, fix it and again click on Compile. In our case, upon deleting the Unknown MADT subtable type lines, there is no more error, and the APIC Table is compiled successfully without any errors.
4. Save the APIC Table using the File>Save option.
Of course, this step is not required for every APIC Table which needs patching, as most of them do not contain any errors and only require patching the Processor ID for fixing the Kernel Panic. However, checking for compiling errors and fixing them is still recommended.
STEP 4: Patching APIC Table
Once you have analyzed the native APIC Table, you're ready to patch it. Typically, the patching involves re-arranging the Processor ID entries in the APIC Table to properly match our DSDT. To patch the APIC Table, you can either use the Clover method or the manual Method. Please note that the manual method is also supported by Clover. However, provided that Clover has already an option for patching the APIC Table, which can patch the APIC Table on the fly in a single click, therefore a cleaner approach and is the preferred method over the manual method for Clover. To patch the APIC Table, follow the steps below.
Here we can see the DSDT and APIC entries, and they are mismatched. While it is possible to edit the DSDT, patching the APIC Table is far easier as it's a much smaller file and the complexity involved is much less. Moreover, hot patching is a lot cleaner approach than patching the DSDT directly. So let's edit the file to properly reflect the DSDT:
While the DSDT is
STEP 5: Dropping the Native APIC Table
Before you inject the newly patched APIC Table, the next step is to drop the native APIC Table to prevent it from loading. Follow the steps below to drop the native APIC Table.
1. Mount your ESP
2. Depending on your bootloader,
For Clover:
1. Open your
2. Add
3. Save your
For OpenCore:
1. Open your
2. Add
3. Save your
NOTE: If you do not have a
STEP 6: Installing the patched APIC Table
The next step is to install the patched APIC Table for fixing the Kernel Panic. Follow the steps below to install the APIC Table.
1. Assuming the ESP is still mounted, copy the patched
2. Depending on your bootloader,
For Clover:
If you're using Clover, copy the patched
For OpenCore:
If you're using OpenCore, copy the patched
3. Save your
STEP 7: Resetting NVRAM
After performing all the above steps, restart your system. It is recommended to reset NVRAM twice at least. Boot via the installer or the target disk and you should be able to boot without any Kernel Panic.
This guide describes how to patch APIC for macOS. This guide is supported by both, i.e Clover and OpenCore Bootloader. By following this guide, you'll be able to patch the APIC Table for booting macOS.
Overview
APIC stands for Advanced Programmable Interrupt Controller. Its parameters are defined in the MADT (Multiple APIC Description Table). If this table is missing the "NMI" section, the system can only boot by setting the kernel parameter cpus=1 or with a patched kernel (Lapic NMI).
On a few systems, some HEDT users may experience a Kernel Panic when booting into macOS, before reaching the installation stage. Although there could be several underlying causes for a Kernel Panic, the panic is related to more cores defined in the APIC Table than actually present. This can also be seen using the verbose mode:
This is because macOS assumes that the first CPU in ACPI is always enabled, which may not always be true for HEDT and Server grade Systems. To fix this issue, you'll need to patch the APIC Table and thereafter, you can boot into macOS. This is mainly relevant for HEDT Systems like X58, X79, X99, and X299 but might be helpful for other systems with higher CPU Core Count.
Initially, to get around this APIC issue, a workaround was introduced in Clover called
PatchAPIC (formerly PatchNMI) option to patch the APIC Table on the fly so the system can boot. If the table is complete already, nothing will be changed. This option still exists for Clover. However, as OpenCore does not have an equivalent of the PatchAPIC option, patching the APIC Table manually is the only way for OpenCore users.The steps mentioned below are only valid if your system has a Kernel Panic relating to the CPU Core count and will not work if your system has a Kernel Panic due to some other cause. Please check the verbose log to ensure you're in the right direction.
Requirements
Following are the requirements for patching APIC Table on macOS. Please ensure you meet the requirements before proceeding with this guide.
| CPU |
|
| Tools |
|
Assumptions:
This guide assumes that you have already some experience with the following. Having some of the following experience can be really helpful when following the guide.
- macOS/OS X Bootable USB with a properly configured EFI
- Basic config.plist editing skills
- Basic MaciASL usage
- Basic Clover/OpenCore knowledge
- Basic knowledge of installing/injecting kexts
Method #1: Using Clover HotPatch
Using Clover Hotpatches, you can patch the APIC Table on the fly. However, this method is limited to Clover bootloader only as OpenCore does not have an equivalent of the PatchAPIC option. To patch the APIC Table using Clover's Hotpatch method, follow the steps below.
1. Mount your ESP
2. Open your
config.plist using any XML editor from the EFI/Clover directory.3. Enable the
Patch APIC option under the Acpi section of your config.plist.4. Save your
config.plist.5. Restart your system for the applied changes to take effect. It is recommended to reset NVRAM twice at least.
Method #2: Using Manual SSDT Patch
Using Clover, APIC can be patched using one single click, on the fly. However, with the introduction of OpenCore, where a majority of ACPI Fixes don't exist unlike Clover, you'll have to patch the APIC Table manually. Although this method is supported by both i.e Clover and OpenCore Bootloader, beginner users may find this method a bit difficult. To patch APIC using the "Manual SSDT Patch", follow the steps below.
STEP 1: Extracting ACPI Tables
The very first step is to extract your native ACPI Tables. We recommend it extracting using Clover, for the highest level of integrity. If you're not aware of how to do that, a guide is already available which is linked below.
GUIDE - How to Extract DSDT/SSDTs
How to Extract DSDT/SSDTs An EliteMacx86 Exclusive Guide - This guide covers the extraction of ACPI sets, (commonly known as DSDT and SSDTs) using Clover. Overview Extracting DSDT/SSDTs is very easy and has minimal requirements. To extract the DSDT/SSDT, follow the steps below. For Clover...
elitemacx86.com
STEP 2: Analyzing the Native APIC Table
Now, we would need to take a look at our native APIC Table. This is required because by examining the APIC Table, we can get to know whether the APIC Table needs to be patched or not and specifically what areas to patch.
Upon taking a look at our native APIC Table:
Here we can see a list of all the CPU threads and info about each one of them. Let's look at the first
[Processor Local APIC] entry:
Here we have some important info, but the most important part is the
Processor ID : 10. This value is what matches up the APIC Table entry with your DSDT which is then passed to macOS to determine the first CPU entry. Here, we can get a glimpse into what might be causing the Kernel Panic.Open your DSDT using MaciASL and search for
Processor in the search box using the Command+F keyboard shortcut.
If you take a look carefully, here we've some important info regarding the first CPU:
Processor (CP00, 0x00, 0x00001810, 0x06)If we check the ACPI Spec, section 19.6.108, we see the info is parsed as follows:
Processor (ProcessorName, ProcessorID, PBlockAddress, PblockLength)Now if we look at the
ProcessorID section, we notice it's 0x00, but this doesn't match up with the first entry in our APIC Table (10) and here we get a clear idea of what's wrong with our APIC Table and why it Kernel Panics. However, these values could be totally different in your case due to the difference in the ACPI Set. So, please look closely at what your values are.STEP 3: Checking for Compiling Errors
Before you start patching the APIC Table to fix the Kernel Panic, you should try to compile the APIC Table and look for any possible errors, like in our case. This is because prior to patching the APIC Table, the native APIC Table can have errors due to several underlying factors such as changes in iasl, bugs in iasl, differences in the compilation environments between our system and the OEM, and sometimes the Table itself and continuing to patch them will cause errors when compiling. These errors must be fixed prior to patching otherwise even after patching the APIC Table, it will not be compiled and saved further, and determining whether the specific patch/changes are causing the errors or the native APIC Table itself can be difficult.
Most of these errors can be fixed manually. In order to determine the error, you can simply 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.
A few errors can be fixed by removing/uncommenting the lines causing the error. However, it depends on whether the line is necessary for the proper operation of the code or not. For example, errors caused by External declarations can be generally removed to fix the error. Please note that each APIC Table can differ from system to system and can have different errors than described in this guide. However, as mentioned above, you must fix such errors so that the Table can compile without errors. If you have any experience with the ACPI spec and some programming experience, it can be really helpful. The goal is to get the native APIC Table to compile without any errors. Once you have the APIC Table that compiles without errors, you can start patching your APIC Table to fix the Kernel Panic.
For a few systems, it can be common to have
Unknown subtable type (MADT) error. The fix is to simply comment out the related subtable type.Let's take an example of our SSDT to check for compiling errors.
1. Open the native APIC Table and click on Compile and look for errors in the Compiler Summary. If there's an error, fix it and again click on Compile. If there are no errors, you can simply skip this step and continue with STEP #4.
In our case when compiling the native APIC Table, it has an Unknown subtable type (MADT) error due to which the SSDT cannot be compiled and therefore needs to be fixed.
Upon checking the line causing errors, we can see the root cause.
2. To fix the issue, we just need to remove the entire Unknown Subtable Type which is causing the issue. In our case, the Unknown Subtable Type line starts from 454 and ends at line 619.
Code:
[228h 0552 1] Subtable Type : 7F [Unknown Subtable Type]
[229h 0553 1] Length : 0C
**** Unknown MADT subtable type 0x7F
[234h 0564 1] Subtable Type : 7F [Unknown Subtable Type]
[235h 0565 1] Length : 0C
**** Unknown MADT subtable type 0x7F
[240h 0576 1] Subtable Type : 7F [Unknown Subtable Type]
[241h 0577 1] Length : 0C
**** Unknown MADT subtable type 0x7F
[24Ch 0588 1] Subtable Type : 7F [Unknown Subtable Type]
[24Dh 0589 1] Length : 0C
**** Unknown MADT subtable type 0x7F
[258h 0600 1] Subtable Type : 7F [Unknown Subtable Type]
[259h 0601 1] Length : 0C
**** Unknown MADT subtable type 0x7F
[264h 0612 1] Subtable Type : 7F [Unknown Subtable Type]
[265h 0613 1] Length : 0C
**** Unknown MADT subtable type 0x7F
[270h 0624 1] Subtable Type : 7F [Unknown Subtable Type]
[271h 0625 1] Length : 0C
**** Unknown MADT subtable type 0x7F
[27Ch 0636 1] Subtable Type : 7F [Unknown Subtable Type]
[27Dh 0637 1] Length : 0C
**** Unknown MADT subtable type 0x7F
[288h 0648 1] Subtable Type : 7F [Unknown Subtable Type]
[289h 0649 1] Length : 0C
**** Unknown MADT subtable type 0x7F
[294h 0660 1] Subtable Type : 7F [Unknown Subtable Type]
[295h 0661 1] Length : 0C
**** Unknown MADT subtable type 0x7F
[2A0h 0672 1] Subtable Type : 7F [Unknown Subtable Type]
[2A1h 0673 1] Length : 0C
**** Unknown MADT subtable type 0x7F
[2ACh 0684 1] Subtable Type : 7F [Unknown Subtable Type]
[2ADh 0685 1] Length : 0C
**** Unknown MADT subtable type 0x7F
[2B8h 0696 1] Subtable Type : 7F [Unknown Subtable Type]
[2B9h 0697 1] Length : 0C
**** Unknown MADT subtable type 0x7F
[2C4h 0708 1] Subtable Type : 7F [Unknown Subtable Type]
[2C5h 0709 1] Length : 0C
**** Unknown MADT subtable type 0x7F
[2D0h 0720 1] Subtable Type : 7F [Unknown Subtable Type]
[2D1h 0721 1] Length : 0C
**** Unknown MADT subtable type 0x7F
[2DCh 0732 1] Subtable Type : 7F [Unknown Subtable Type]
[2DDh 0733 1] Length : 0C
**** Unknown MADT subtable type 0x7F
[2E8h 0744 1] Subtable Type : 7F [Unknown Subtable Type]
[2E9h 0745 1] Length : 0C
**** Unknown MADT subtable type 0x7F
[2F4h 0756 1] Subtable Type : 7F [Unknown Subtable Type]
[2F5h 0757 1] Length : 0C
**** Unknown MADT subtable type 0x7F
[300h 0768 1] Subtable Type : 7F [Unknown Subtable Type]
[301h 0769 1] Length : 0C
**** Unknown MADT subtable type 0x7F
[30Ch 0780 1] Subtable Type : 7F [Unknown Subtable Type]
[30Dh 0781 1] Length : 0C
**** Unknown MADT subtable type 0x7F
[318h 0792 1] Subtable Type : 7F [Unknown Subtable Type]
[319h 0793 1] Length : 0C
**** Unknown MADT subtable type 0x7F
[324h 0804 1] Subtable Type : 7F [Unknown Subtable Type]
[325h 0805 1] Length : 0C
**** Unknown MADT subtable type 0x7F
[330h 0816 1] Subtable Type : 7F [Unknown Subtable Type]
[331h 0817 1] Length : 0C
**** Unknown MADT subtable type 0x7F
[33Ch 0828 1] Subtable Type : 7F [Unknown Subtable Type]
[33Dh 0829 1] Length : 0C
**** Unknown MADT subtable type 0x7F
[348h 0840 1] Subtable Type : 7F [Unknown Subtable Type]
[349h 0841 1] Length : 0C
**** Unknown MADT subtable type 0x7F
[354h 0852 1] Subtable Type : 7F [Unknown Subtable Type]
[355h 0853 1] Length : 0C
**** Unknown MADT subtable type 0x7F
[360h 0864 1] Subtable Type : 7F [Unknown Subtable Type]
[361h 0865 1] Length : 0C
**** Unknown MADT subtable type 0x7F
[36Ch 0876 1] Subtable Type : 7F [Unknown Subtable Type]
[36Dh 0877 1] Length : 0C
**** Unknown MADT subtable type 0x7F3. Click on Compile and look for errors in the Compiler Summary. If the error persists, fix it and again click on Compile. In our case, upon deleting the Unknown MADT subtable type lines, there is no more error, and the APIC Table is compiled successfully without any errors.
4. Save the APIC Table using the File>Save option.
Of course, this step is not required for every APIC Table which needs patching, as most of them do not contain any errors and only require patching the Processor ID for fixing the Kernel Panic. However, checking for compiling errors and fixing them is still recommended.
STEP 4: Patching APIC Table
Once you have analyzed the native APIC Table, you're ready to patch it. Typically, the patching involves re-arranging the Processor ID entries in the APIC Table to properly match our DSDT. To patch the APIC Table, you can either use the Clover method or the manual Method. Please note that the manual method is also supported by Clover. However, provided that Clover has already an option for patching the APIC Table, which can patch the APIC Table on the fly in a single click, therefore a cleaner approach and is the preferred method over the manual method for Clover. To patch the APIC Table, follow the steps below.
Here we can see the DSDT and APIC entries, and they are mismatched. While it is possible to edit the DSDT, patching the APIC Table is far easier as it's a much smaller file and the complexity involved is much less. Moreover, hot patching is a lot cleaner approach than patching the DSDT directly. So let's edit the file to properly reflect the DSDT:
While the DSDT is
0x00, the APIC does not need the 0x prefix so our final value in the APIC Table would be simply 00. Please note that this value may differ in your case and these values are different on a case-to-case basis. It is always recommended to analyze your APIC and DSDT Table first, before proceeding with patching.STEP 5: Dropping the Native APIC Table
Before you inject the newly patched APIC Table, the next step is to drop the native APIC Table to prevent it from loading. Follow the steps below to drop the native APIC Table.
1. Mount your ESP
2. Depending on your bootloader,
For Clover:
1. Open your
config.plist using any XML editor from the EFI/Clover directory.2. Add
APIC entry into the Signature key under the Acpi>Drop Tables section of your config.plist. If you're using the Sorted Order configuration, add SSDT-APIC.aml to the list.3. Save your
config.plist.For OpenCore:
1. Open your
config.plist using any XML editor from the EFI/OC directory.2. Add
APIC entry into the TableSignature key under ACPI>Delete section of your config.plist and also set the entry to Enabled.3. Save your
config.plist.NOTE: If you do not have a
config.plist yet, ensure to include it in your config.plist when you head back to the Clover or OpenCore Installation Guide.STEP 6: Installing the patched APIC Table
The next step is to install the patched APIC Table for fixing the Kernel Panic. Follow the steps below to install the APIC Table.
1. Assuming the ESP is still mounted, copy the patched
APIC.aml SSDT.2. Depending on your bootloader,
For Clover:
If you're using Clover, copy the patched
APIC.aml SSDT to EFI/Clover/ACPI/patched directory.For OpenCore:
If you're using OpenCore, copy the patched
APIC.aml SSDT to EFI/OC/ACPI directory. You'll also need to add the ACPI entries in ACPI>Add section of your config.plist.3. Save your
config.plist.STEP 7: Resetting NVRAM
After performing all the above steps, restart your system. It is recommended to reset NVRAM twice at least. Boot via the installer or the target disk and you should be able to boot without any Kernel Panic.
Last edited:
