A Beginner's Guide to Creating a Custom USB SSDT

[UtterDisbelief]

So I initially thought I had configured things correctly, I created a kext with Hackintool back on High Sierra. I then upgraded to Mojave and checked with Feartech and he said I could use the kext I created in HS

I was then checking things and I noticed that I had configured my 15 ports including PR11 and PR21 which are on EH01 and EH02, they show as “AppleUSB20InternalHub” - I included these when I created the kext with Hackintool and I now think this is wrong as everything should be on XHC no?

I thought I would start from scratch as I said but I think I’m now confusing myself more

I hope this makes sense

No problem. Going back to basics -

Apple impose a USB 15-port limit. Apple use an XHCI controller. So we try to emulate those if we can.

There are so many PC motherboards we sometimes have to compromise. Generally they have many more USB ports so we aim to only configure 15. And in preference use the XHCI controller. To do this we initially use USBInjectAll and a port-limit removal patch (remember macOS only sees 15 otherwise) so we can see them and choose which ones we want. Then we write a template to specify which ports are activated and how they should work. To run this template we use USBInjectAll again OR we use Hackintool's USBPorts.kext (There is a third method but we will ignore it for now).

In your case the Z87 has 14-ports available - 8x USB2 and 6x USB3. Because the USB3 ports can also act as USB2 ports we need two configurations for each, totalling 20x ports. Logic dictates we then should disable 5x ports to get to our target 15.

On your motherboard, personally I would not use the EHC renames you have in your config.plist. I don't have access to a Z87 but I would hope that if you do remove the renames the EHC controller will become invisible to macOS, leaving just the XHC ports to play with. Try it and let me know etc.

Next you can decide which of your HS01 to HS14 and SS01 to SS06 ports you are going to use by doing the port-discovery shown in this guide way back at post #1.

Create your template and put it in - EFI/CLOVER/ACPI/patched - remove or temporarily disable the port-limit patch and reboot. Hopefully you then have a fully working USB sub-system.

OR after removing the EHC controller, by using Hackintool you can select either of its two methods to configure your ports instead. The actual technology behind both processes is the same, just wrapped-up in different ways. The method outlined here is more hands-on but also more transparent.

The choice, as they say, is yours

 

[Humanate]

No problem. Going back to basics -

Apple impose a USB 15-port limit. Apple use an XHCI controller. So we try to emulate those if we can.

There are so many PC motherboards we sometimes have to compromise. Generally they have many more USB ports so we aim to only configure 15. And in preference use the XHCI controller. To do this we initially use USBInjectAll and a port-limit removal patch (remember macOS only sees 15 otherwise) so we can see them and choose which ones we want. Then we write a template to specify which ports are activated and how they should work. To run this template we use USBInjectAll again OR we use Hackintool's USBPorts.kext (There is a third method but we will ignore it for now).

In your case the Z87 has 14-ports available - 8x USB2 and 6x USB3. Because the USB3 ports can also act as USB2 ports we need two configurations for each, totalling 20x ports. Logic dictates we then should disable 5x ports to get to our target 15.

On your motherboard, personally I would not use the EHC renames you have in your config.plist. I don't have access to a Z87 but I would hope that if you do remove the renames the EHC controller will become invisible to macOS, leaving just the XHC ports to play with. Try it and let me know etc.

Next you can decide which of your HS01 to HS14 and SS01 to SS06 ports you are going to use by doing the port-discovery shown in this guide way back at post #1.

Create your template and put it in - EFI/CLOVER/ACPI/patched - remove or temporarily disable the port-limit patch and reboot. Hopefully you then have a fully working USB sub-system.

OR after removing the EHC controller, by using Hackintool you can select either of its two methods to configure your ports instead. The actual technology behind both processes is just the same, just wrapped-up in different ways. The method outlined here is more hands-on but also more transparent.

The choice, as they say, is yours

Thanks. I understand about the 15 port limit and that we use the XHCI controller

I have the rename from when @RehabMan helped me when I was back on El Capitan, I think it is needed. I removed the rename and I attach "iMac1" ioReg which shows EHC1 and EHC2 active and "iMac2" which is with the patch restored with these routed to EH01 and EH02. By the way, anyone know what happened to rehabman, he seems to have disappeared, hope he's not actually in rehab!

I think I can do the SSDT, I understand that part. My question is should I have PR11 and PR21 showing on EHC1/2 after the rename, is this normal. I may head over to the more advanced thread or Hackintool also (no offence - I appreciate your help!) to try and develope my understanding

 

[kodadog]

I'm working on the USB on my GA-H77N-WIFI | i3 3225 | HD 4000. I'm following your guide! Mixing methods has messed me up before.

All my USB ports seem to be working, but I'm expect instability to creep back in over time. I can't get rid of all the extra USB2 ports that show up in IOReg. I've started from scratch a few times and get to the same end result. I've made the SSDT-USB.aml and the USB3 ports properly show up.. . but ALL the USB2 ports keep showing up in IOReg... not just the ones in the SSDT. I've attached the problem reporting files. I hope you can help me find where I've got it wrong. Thanks.

 

[UtterDisbelief]

I'm working on the USB on my GA-H77N-WIFI | i3 3225 | HD 4000. I'm following your guide! Mixing methods has messed me up before.

All my USB ports seem to be working, but I'm expect instability to creep back in over time. I can't get rid of all the extra USB2 ports that show up in IOReg. I've started from scratch a few times and get to the same end result. I've made the SSDT-USB.aml and the USB3 ports properly show up.. . but ALL the USB2 ports keep showing up in IOReg... not just the ones in the SSDT. I've attached the problem reporting files. I hope you can help me find where I've got it wrong. Thanks.

Okay.

Note: The Beginner's Guide does not cover how to configure both EHC and XHC controllers in the same build. For the latest macOs versions you should only need XHC unless it is not present on the motherboard.

You have covered three motherboards so far in this thread - ASUS Sabertooth X79, Gigabyte GA-H270 Gaming 3 and now a Gigabyte GA-H77N-Wifi. It's confusing. We have not seen an IORegEx for the latest, nor what is in its Drive: Library/Extensions folder.

I see in your latest SSDT-USB.aml you have configured both the XHC and EHC controllers, these are the 8086_1e26, 8086_1e2d & (XHC) 8086_1e31.

Back to basics:

Step 1) Remove any Hackintool configuration files for now (USBPorts.kext, and/or SSDTs).

Step 2) USBInjectAll.kext into EFI/CLOVER/kexts/Other

Step 3) If required edit a Port-lmit removal patch into config.plist (which one is dependant on the macOS version you are using. Not needed if your motherboard has less than 15 ports).

Step 4) Do NOT use FakePCIID_XHCIMux.kext. (Rebuild caches if you have removed any kexts).

Step 5) Do NOT have an EHC rename pair in your config.plist. Disable or remove.

Step 6) Remove the present SSDT-USB.aml but store safely elsewhere in case needed again.

Step 7) Reboot and check your IORegistryExplorer output for the XHC controller. Check if the EHC controller is present. You should see all available USB ports, hopefully 18 on XHC, maybe a couple extra.

To configure:

Step 1) Create an SSDT template with only the XHC device ID present (8086_1e31) but with all the ports you require.

Step 2) Compile to SSDT-USB.aml, place in CLOVER/ACPI/patched.

Step 3) Disable or Remove the port-limit removal patch but leave USBInjectAll.kext in place.

Step 4) Reboot and check IORegistryExplorer again.

 

[kodadog]

We have not seen an IORegEx for the latest, nor what is in its Drive: Library/Extensions folder.

I ran gen_debug but I didn't check the previous debug.zip file... I didn't realize it was missing items. This newer one has everything.

Step 7) Reboot and check your IORegistryExplorer output for the XHC controller. Check if the EHC controller is present. You should see all available USB ports, hopefully 18 on XHC, maybe a couple extra.

XHC shows HSP1-4 and SSP1-4 (I need #3 & 4 of each). EHC1 shows 3 ports: PRT1,3 & 8, EHC2 shows 6 ports: PR11-15.

Step 1) Create an SSDT template with only the XHC device ID present (8086_1e31) but with all the ports you require.

Now I make an SSDT with only the XHC device ID (8086_1e31) even though the USB2 ports are under EHC1 (8086_1e26) & EHC2 (8086_1e2d)? Is that right? I am definitely confused. I really appreciate your help. Thank you.

 

[UtterDisbelief]

I ran gen_debug but I didn't check the previous debug.zip file... I didn't realize it was missing items. This newer one has everything.

XHC shows HSP1-4 and SSP1-4 (I need #3 & 4 of each). EHC1 shows 3 ports: PRT1,3 & 8, EHC2 shows 6 ports: PR11-15.


Now I make an SSDT with only the XHC device ID (8086_1e31) even though the USB2 ports are under EHC1 (8086_1e26) & EHC2 (8086_1e2d)? Is that right? I am definitely confused. I really appreciate your help. Thank you.

Hi there.

Not all XHC controllers are the same. Like everything they have developed over time. Back in 2012 the H77 had an XHCI controller which featured only 4x USB3.0 ports. The included EHCI controller featured a useful 10x USB2.0 ports. So to give a motherboard a full compliment of ports, the manufacturer would use both controllers.

The reason I wanted you to try without EHCI was simply to clear away clutter and see what your configuration was. I don't think you've listed the kexts you have in your Drive: Library/Extension folder when I've asked. No problem; that's your choice - but I'm working in the dark and can't see the whole picture. I was just trying to work around that.

I don't think you've mentioned which version of macOS you are using either.

Your IORegEx USB port setup looks fine - 8x ports on the XHC and 2x ports on the EHCs So yes, put all three controllers in your SSDT template - EH01, EH02 & XHC - by using their Product/DeviceIDs.

You say -

... but I'm expect instability to creep back in over time...

- but that doesn't tell me anything about a specific problem you are experiencing, so I can't address it.

The H77 Mini-ITX motherboard only has 14x ports - 4x USB3 (double these) plus 6x USB2. So no need for the Port-Limit Removal Patch in this example.

The way to get all your USB ports working is to use USBInjectAll.kext to make them available and then create an SSDT to configure the 14x maximum ports you want to use. In this way the SSDT can be thought of as a configuration file for USBInjectAll. Other methods use other means, for example directly patching ACPI or using a codeless kext.

Perhaps if you could be precise about what the problem is you are having we can then address that .

Incidentally you do have a port-limit removal patch in place - it's not needed - and it is only for El Capitan.

 

[kodadog]

I don't think you've listed the kexts you have in your Drive: Library/Extension folder

Sorry, I thought the the L/E list was included in gen_debug files. Also I'm on El Capitan.

L/E: ACS6x.kext / AppleIntelE1000e.kext / ArcMSR.kext / AtherosE2200Ethernet.kext / ATTOCelerityFC8.kext / ATTOExpressSASHBA2.kext / ATTOExpressSASRAID2.kext / BJUSBLoad.kext / CalDigitHDProDrv.kext / CIJUSBLoad.kext / FakeSMC.kext / HighPointIOP.kext / HighPointRR.kext / PromiseSTEX.kext / realtekALC.kext / RealtekRTL8111.kext / SoftRAID.kext

One problem I've been trying to solve is that I always ended up with an IOReg showing more USB ports than I used (and more than 15). And my understanding is that this leads to instability.... intermittent USB connection problems - which I've had. I've attached the SSDT that seems to be working for me on the ga-h77n board. With this SSDT the IOReg shows just the USB ports that are actually being used without extras! I think the intermittent USB problems I've seen may be solved. Thanks for your help.

 

[UtterDisbelief]

Sorry, I thought the the L/E list was included in gen_debug files. Also I'm on El Capitan.

L/E: ACS6x.kext / AppleIntelE1000e.kext / ArcMSR.kext / AtherosE2200Ethernet.kext / ATTOCelerityFC8.kext / ATTOExpressSASHBA2.kext / ATTOExpressSASRAID2.kext / BJUSBLoad.kext / CalDigitHDProDrv.kext / CIJUSBLoad.kext / FakeSMC.kext / HighPointIOP.kext / HighPointRR.kext / PromiseSTEX.kext / realtekALC.kext / RealtekRTL8111.kext / SoftRAID.kext

One problem I've been trying to solve is that I always ended up with an IOReg showing more USB ports than I used (and more than 15). And my understanding is that this leads to instability.... intermittent USB connection problems - which I've had. I've attached the SSDT that seems to be working for me on the ga-h77n board. With this SSDT the IOReg shows just the USB ports that are actually being used without extras! I think the intermittent USB problems I've seen may be solved. Thanks for your help.

Okay, thanks for the clarification. That helps.

Glad all is working okay now. Well done on your work

Notes:

1) you have only configured 2x of your 4x USB3.0 ports - I'm guessing they are the back-panel ones under the PS/2 socket.

2) the motherboard has 4x back-panel USB2.0 ports plus 2x internally for a total of 6x, so the extra 2x showing on your "Hub"s must be a mix of the EHC and XHC ports to get to those 8x ports. If that's the case then I would want to do-away with those Hubs as they just confuse things.

I'd do port discovery again. Remember to remove any SSDTs already in place. Although not strictly needed, I'd also use a port-limit removal patch for completeness sake. Then test all ports using a USB2.0 memory stick and again with a USB3.0 memory stick, and make my list from IORegistryExplorer.

Although it is possible Gigabyte might have partitioned controllers onto hubs with your motherboard I see no reason why as the numbers are low and it's the same chipset. But hey, you never know!

Also I'd try the simpler SSDT template by @ammulder at the beginning of the guide rather than the all-encompassing one by @RehabMan.

 

[kodadog]

1) you have only configured 2x of your 4x USB3.0 ports - I'm guessing they are the back-panel ones under the PS/2 socket.

Correct! The other 2 internal USB3 ports are not being used.

 

[r2tincan]

In addition EHCI controllers need two extra kexts. Install them with KextBeast - FakePCIID.kext & FakePCIID_XHCIMux.kext . This is because as an older controller it needs help communicating with the latest macOS.

Immediately after I install these USB completely stops working on my system. I have installed the XHCI unsupported kext as well as the InjectAll kext already.

10.13.6 with an X99 board.
Any ideas?