The New Beginner's Guide to USB Port Configuration

[UtterDisbelief]

Hi @UtterDisbelief thank you for your guide, I just discovered it... Have been using USBInjectAll with SSDT-UIAC on my NUC8 and wanted to ask a couple of setup questions, if you know (or anyone else of course, is welcome).

1. You mention on your first post:
The physical port is the same, but how it is enumerated is different depending on what type of device is plugged-in - USB2.0 is an HS** port and USB3.0/3.1 is an SS** port. So as you can see, a single, physical USB3 port counts as 2x ports towards our 15-limit because either type of device can be plugged in to it.

I agree on that of course, but I still wanted to ask you if, for the sake of being 100% accurate on later computers without EHCI controller but only XHCI, we should (or not) mark all HS0x ports as USB2 instead of USB3 controller type? Indeed HS probably stands for "High Speed" but as USB 2.0 devices are mapped only to HS0x ports and USB 3.0 devices show as SS0x ports (in IOReg) is it better to tell the system that HS0x is eventually a USB2 type controller? (on Hackintool, prior to exporting) Any ideas why we should (not)? Just to learn...

2. And speaking of learning (part of Hackintoshing joy) it was my prior understanding to reading your guide that USBPorts.kext (being a binary-less kext) was replacing SSDT-UIAC.aml only; didn't realise we don't need USBInjectAll.kext anymore! Is this valid for Mojave or only Catalina and forward? And do you understand the mechanics on how its special Info.plist manages to "force" USB port names etc. to the system without the need of a binary kext such as USBInjectAll.kext? It's very interesting how this is achieved, to my opinion!

Thank you all for your input!

Hi there.

Okay...

1) On a chipset with only an XHCI controller a USB2 port is described by its UsbConnector type. A black, USB2-only port has fewer electrical contacts in it than a blue or red USB2/USB3 port. So even though we are configuring an HS** USB2 port, if it is on a blue USB3 socket we still use UsbConnector type "3". So to answer your question: no.

2) True, with a USBPorts.kext you do not need either USBInjectAll.kext or SSDT-UIAC.aml. You may still need SSDT-EC.aml though.

Yes, I do understand. Even though USBPorts is an "empty" kext container it is still loaded/injected in the same way. As it has no core executable the surprising bonus is that it does not show up in kextstat or the logs, and doesn't get blocked by Catalina. Yet.

USBPorts.kext works for all macOS versions though I have only tested back to Sierra myself.

Hope that helps.

 

[konsti]

So even though we are configuring an HS** USB2 port, if it is on a blue USB3 socket we still use UsbConnector type "3". So to answer your question: no.
[...]
As it has no core executable the surprising bonus is that it does not show up in kextstat or the logs, and doesn't get blocked by Catalina.

Thank you very much for your insight, I didn't think of the actual electrical connectivity parameter, you are so correct. So indeed, HS0x makes sense to add them as UsbConnector=3

Yes, it's surprising that the kext works, and despite liking the DSL/AML version as I can read it better on a simple text editor, this "kext" solution seems more flexible i.e. any change doesn't require to mess with a perfectly working Clover EFI folder contents! Many thanks for confirming.

A final question if I may; do you or any member here, have any idea or experience if the USBPorts.kext structure supports dual XHCI interfaces? One for USB 3.0 and the other for USB 3.1, as it's defined in my personally edited and working SSDT-UIAC that I am attaching here for my Intel NUC8? Many thanks again!

 

[headkaze]

A final question if I may; do you or any member here, have any idea or experience if the USBPorts.kext structure supports dual XHCI interfaces? One for USB 3.0 and the other for USB 3.1, as it's defined in my personally edited and working SSDT-UIAC that I am attaching here for my Intel NUC8? Many thanks again!

All it does is generate a codeless kext based on what it finds in IORegistry. With your hackintosh booted using your current SSDT-UIAC try the USB export function from Hackintool and have a look at the Info.plist inside USBPorts.kext to see if it's included them.

 

[UtterDisbelief]

Thank you very much for your insight, I didn't think of the actual electrical connectivity parameter, you are so correct. So indeed, HS0x makes sense to add them as UsbConnector=3

Yes, it's surprising that the kext works, and despite liking the DSL/AML version as I can read it better on a simple text editor, this "kext" solution seems more flexible i.e. any change doesn't require to mess with a perfectly working Clover EFI folder contents! Many thanks for confirming.

A final question if I may; do you or any member here, have any idea or experience if the USBPorts.kext structure supports dual XHCI interfaces? One for USB 3.0 and the other for USB 3.1, as it's defined in my personally edited and working SSDT-UIAC that I am attaching here for my Intel NUC8? Many thanks again!

All it does is generate a codeless kext based on what it finds in IORegistry. With your hackintosh booted using your current SSDT-UIAC try the USB export function from Hackintool and have a look at the Info.plist inside USBPorts.kext to see if it's included them.

I would also add - check the value you are using for "port-count" on 8086_9ded.

 

[Covalt]

Yes, you are correct, the 4x USB2 ports your motherboard has are those two headers - F_USB1 and F_USB2. As you know each header is actually 2x ports. Depending on what type of plug your Fenvi came with you may or may not be able to select each (a 9-pin plug only accesses 1x port and blocks the other. A 5-pin plug can be moved to each one etc).

To be honest I'm surprised that neither of these ports is working correctly for you. Although it doesn't look as though you have, have you installed any third-party USB-related kexts anywhere? XHCI-unsupported, GenericUSBXHCI or FakePCIID_XHCIMux? Any SSDT patches? These can cause the "ghosting" we are seeing.

Of course, my suggestion now is to follow this guide and complete your USB configuration. That way macOS is not seeing something it doesn't understand.

Run Hackintool and see what USB configuration it shows (as per the guide). Remember you have a Thunderbolt controller in the mix here and it will "attach" to a couple of conventional USB3 ports, because they work with USB3 devices too etc.

Post a screengrab of the Hackintool USB pane.

I went back to follow the guide and use Hackintool to remove USB ports, but where I get hung up again is being able to identify which ports are what. At this point I've been able to identify HS/SS 03-06 (via the USB 2/3 drive as you suggest), but beyond those I can't figure out how to identify HS/SS 01-02, 07-14, and USR1, USR2.
I assume it's because when I plug in my USB drive it works but doesn't show up in Hackintool because it's going through a hub?
Should I maybe just take my best guess and start deleting USB ports with Hackintool and then see what doesn't work?
Or is there another way to identify these other USB ports?

 

[UtterDisbelief]

I went back to follow the guide and use Hackintool to remove USB ports, but where I get hung up again is being able to identify which ports are what. At this point I've been able to identify HS/SS 03-06 (via the USB 2/3 drive as you suggest), but beyond those I can't figure out how to identify HS/SS 01-02, 07-14, and USR1, USR2.
I assume it's because when I plug in my USB drive it works but doesn't show up in Hackintool because it's going through a hub?
Should I maybe just take my best guess and start deleting USB ports with Hackintool and then see what doesn't work?
Or is there another way to identify these other USB ports?
View attachment 453942

Remember some ports are on a different controller and may not show.

Move the Bluetooth cable to a different motherboard header to see if it appears in Hackintool.

Understood, it can be difficult to identify internal ports unless you have something to plug in there. You can usually work them out from the logic of numbering too though.

What we need to do with priority though is get the Bluetooth connection working reliably.

Check BIOS for XHCI Handoff Enabled.

Search our Forums to see if anyone else has used the same motherboard.

 

[konsti]

All it does is generate a codeless kext based on what it finds in IORegistry. With your hackintosh booted using your current SSDT-UIAC try the USB export function from Hackintool and have a look at the Info.plist inside USBPorts.kext to see if it's included them.

That is almost how I found out that a second XHCI controller is supported in SSDT-UIAC, as another user in another forum had posted his own AML file. So far all templates indicated only EH01, EH02 and multiple XHC controllers based on chipset ID but wasn't sure more than one was allowed. In that user's file, I saw a main reference "XHC" for the main USBv3.0 controller (instead of using device ID e.g. 8086_9ded) and the second tree was the second USBv3.1 controller, same as me in this case (8086_15db) that I confirmed in my IORegistryExplorer. Thank you, nevertheless, for confirming!

I would also add - check the value you are using for "port-count" on 8086_9ded

Thank you @UtterDisbelief, I had triple checked the UIAC list before activating it, it is correct as the last port reference in my active H/W is SS04 that has port "number" of 0x10; the subsequent SS05 and SS06 I left them commented out as they don't exist on my NUC8 but still wanted to keep them in DSL file as a "template" for possibly other (learning) need and to remind me that "port-count" is not a linear counter (total of ports enabled) but a reference to the last actual port visible on the Haxie...

 

[Covalt]

Remember some ports are on a different controller and may not show.

Move the Bluetooth cable to a different motherboard header to see if it appears in Hackintool.

Understood, it can be difficult to identify internal ports unless you have something to plug in there. You can usually work them out from the logic of numbering too though.

What we need to do with priority though is get the Bluetooth connection working reliably.

Check BIOS for XHCI Handoff Enabled.

Search our Forums to see if anyone else has used the same motherboard.

Searched around and did end up finding a USB map for the Xtreme version of my board.
It accounts for most ports that show up in Hackintool, with the exception of:
HS01, HS09-12, USR1, USR2, SS07-10.
I am content to disable MOST USB ports just to get this thing working honestly.

I wonder if Bluetooth might "partially" work and just needs me to get under the 15 limit because today my Apple Watch asked me if I want to trust the Hackintosh, and Apple Watch communicates via Bluetooth, right?

Back to the original guide - Step 5 for OpenCore instructs to replace USBPorts.kext -AND- to amend the kext name in my config.plist.. remove PLR_patches, etc.
That second part is new to me (I had help with the original setup from @pastrychef) so I don't actually know what steps to take to amend the kext name.
If I open my config.plist with XCode, I can find 14 items under Kernel > Add, but I don't see any of those as USBPorts.kext. (though I do see Item 8 is USBInjectAll.kext).
Is this where I am adding USBPorts.kext?
Or am I way off?

Also, XHCI Handoff is enabled in BIOS.

Made my own USB map for my Z390 Aorus Xtreme below:

 

[UtterDisbelief]

Searched around and did end up finding a USB map for the Xtreme version of my board.
It accounts for most ports that show up in Hackintool, with the exception of:
HS01, HS09-12, USR1, USR2, SS07-10.
I am content to disable MOST USB ports just to get this thing working honestly.

I wonder if Bluetooth might "partially" work and just needs me to get under the 15 limit because today my Apple Watch asked me if I want to trust the Hackintosh, and Apple Watch communicates via Bluetooth, right?

Back to the original guide - Step 5 for OpenCore instructs to replace USBPorts.kext -AND- to amend the kext name in my config.plist.. remove PLR_patches, etc.
That second part is new to me (I had help with the original setup from @pastrychef) so I don't actually know what steps to take to amend the kext name.
If I open my config.plist with XCode, I can find 14 items under Kernel > Add, but I don't see any of those as USBPorts.kext. (though I do see Item 8 is USBInjectAll.kext).
Is this where I am adding USBPorts.kext?
Or am I way off?

Also, XHCI Handoff is enabled in BIOS.

Made my own USB map for my Z390 Aorus Xtreme below:
View attachment 454042

Good work so far

For OpenCore remember you have to positively declare the kexts to load and the path to their executable. As you are removing USBInjectAll.kext at this point then just rename USBInjectAll to USBPorts - BUT - there is no executable in USBPorts.kext so you can remove that field.

To give you a visual example, here is that section as viewed in OpenCore Configurator:

 

[Covalt]

Good work so far

Hah, thanks for the encouragement.. I need it.
Okay, I removed a whole lot to get down to 15 ports, exported the USBPorts.kext file, dropped it in my EFI (replacing the old) and deleted USBInjectAll.kext from the same folder.
Then used OpenCore Config to rename USBInjectAll.kext to USBPorts.kext, and I removed the ExecutablePath field.
Also un-ticked XhciPortLiimit.

Restarted to test things out. Bluetooth isn't working, but it is trying to. I was able to connect my keyboard, but then it drops. Even my wired keyboard is wigging out a bit (repeating strokes, ignoring others). Also tried to connect to my bluetooth Airpods; same experience - it'd connect, but then drop almost immediately.

Dropping a screenshot of Hackintool with the remaining USB ports as well as my config.plist in OpenCore Config.