The New Beginner's Guide to USB Port Configuration

[Edhawk]

Have you changed any of the USB settings in your Bios, i.e. disabled the USB3 device?

 

[10tacle]

I haven't changed anything in my Bios, but since we're running out of ideas I'll gladly double check and report back.

What I did change on the other hand is my Quirks section, I just compared mine to UtterDisbelief's screenshot from page 1 and disabled PowerTimeoutKernelPanic. Not sure if that's relevant.

I also gave Dortania's guide another read and regarding USBInjectAll I noticed this: 'We need this kext to make sure any ports not defined in ACPI will still show up in macOS, note that this shouldn't be required on Skylake and newer as the USB ports are defined within ACPI.'
I just tested enabling XPL without UIA and this time my ports aren't dead... minor step forward, still no SS ports though.

I double checked if I need any renames, but according to these lines, I don't.

 

[UtterDisbelief]

Coming from this thread, I'm about to redo all the port mapping steps from scratch as it may be a reason for my power issues.
Problem is, I've been on Big Sur since 11.4 came out (I'm on 11.5.1 right now) and as long as XhciPortLimit is enabled, all of my USB ports stop working (except for one). Thus making it impossible to do the port mapping properly.
I could simply leave XPL turned off, but I assume that this patch has to be some meaning, otherwise it wouldn't be part of the guide? However, as @Edhawk pointed out in the other thread, only my first 15 ports are active no matter what we tried.

If I ignore that and try to map my ports anyway (USBInjectAll present and enabled, while XhciPortLimit remains off), all of my ports respond as HS, but never SS, even though 4 of them are definitely USB 3 ports. I tried both USB 2 and USB 3 devices, yet it's always HS (plus, there is at least one USB 3 port that isn't even responding at all, unless I plug in a USB 2 device).

This doesn't seem right at all and I'm not sure if there's much sense in proceeding.

Is this due to the missing XhciPortLimit patch?
Any ideas?

Unfortunately there have been issues with the XhciPortLimit quirk since Big Sur 11.3 was released.

USBInjectAll.kext without a port-limit removal patch of some kind does not show any more ports than if it wasn't installed. However it does offer a lot of extra functionality should it be needed.

By default macOS allows just 15x USB ports in total, however a Z370 chipset has 24x. Each of these has a unique address and the first 14x are the HS** USB2 ports, leaving room in the standard 15 for just one USB3 port. The rest are ignored.

This is what you will see without any further configuration.

To see all ports, including those beyond the first 15, we use a port-limit removal patch, or the XhciPortLimit quirk.

Your screengrab in post #1249 shows this full list. It may not be up to date. Use the Broom icon at the bottom of the Hackintool USB window to clear the decks, and then the Circular-Arrows to refresh the display. See if anything changes.

So what to do now?

You can manually create a USB SSDT configuration file and use that instead. Once done you can actually export a new USBPorts.kext from Hackintool and swap to that. A good idea.

Luckily the Z370 chipset has a very specific logic to the way the ports are addressed and you can "guess" the addresses for the SS** ports directly from the HS** ports without having to actually "see" them.

If anything is not clear, just ask.

 

[c-o-pr]

By default macOS allows just 15x USB ports in total, however a Z370 chipset has 24x. Each of these has a unique address and the first 14x are the HS** USB2 ports, leaving room in the standard 15 for just one USB3 port. The rest are ignored.

The language here is somewhat overly narrow to assumption of the tools used.

There clearly is support for more than 15 ports, or expansion hubs would make no sense on Mac.

The limit is relative to the point of attachment to bus: 15 at first tier (so to speak)

Look at USBmap

GitHub - corpnewt/USBMap: Python script for mapping USB ports in macOS and creating a custom injector kext.

Python script for mapping USB ports in macOS and creating a custom injector kext. - corpnewt/USBMap

github.com

//Python script for mapping USB ports in macOS and creating a custom injector kext.//

This tool helps you list, identify, and select the 1st tier ports you want to enable, so you get the best fit to your needs.

By selecting carefully you can ensure essential ports are available such as audio controller, skip onboard decorative case LED controller, and reduce USB2 assignments to ensure onboard hubs and USB3 are enabled so you get best layout for your needs.

One of the useful things it does is help you find IDs of specific ports, so you can winnow the ports you don't need.

It's not trivial but it's very comprehensible,

The key aspects for new user are as follows:

1. It creates a kext that enforces the map, after helping you ID ports. You need to study your mainboard devices to understand its report. There is a basic arrangement to board/ID assignments you have to learn for your board. Finding ports involves plugging in a device with recognizable signature and updating the report, and locating the sig in the report. A bit clumsy but very workable.

2. USB2 and USB3 count as separate ports even though they share a socket

3. Some ports have no socket, e.g, audio or onboard hub. Some are board headers

4. Port ID assignment requires setting the proper port type #, which varies per point 3. You'll have to read guide as I can't recall off top of my head.

THIS APPROACH OBVIATES USBInjectAll and its lore/pitfalls.
*** Get rid of USBInjectAll unless you know you need it.

You have to play with this a little to learn/find your layout, so make a diagram to guide your work. Later it's not hard to update / change because your board doesn't change.

I use this with OpenCore on my kit and it works well.

 

[UtterDisbelief]

The language here is somewhat overly narrow to assumption of the tools used.

There clearly is support for more than 15 ports, or expansion hubs would make no sense on Mac.

The limit is relative to the point of attachment to bus: 15 at first tier (so to speak)

Look at USBmap

GitHub - corpnewt/USBMap: Python script for mapping USB ports in macOS and creating a custom injector kext.

Python script for mapping USB ports in macOS and creating a custom injector kext. - corpnewt/USBMap

github.com

//Python script for mapping USB ports in macOS and creating a custom injector kext.//

This tool helps you list, identify, and select the 1st tier ports you want to enable, so you get the best fit to your needs.

By selecting carefully you can ensure essential ports are available such as audio controller, skip onboard decorative case LED controller, and reduce USB2 assignments to ensure onboard hubs and USB3 are enabled so you get best layout for your needs.

One of the useful things it does is help you find IDs of specific ports, so you can winnow the ports you don't need.

It's not trivial but it's very comprehensible,

The key aspects for new user are as follows:

1. It creates a kext that enforces the map, after helping you ID ports. You need to study your mainboard devices to understand its report. There is a basic arrangement to board/ID assignments you have to learn for your board. Finding ports involves plugging in a device with recognizable signature and updating the report, and locating the sig in the report. A bit clumsy but very workable.

2. USB2 and USB3 count as separate ports even though they share a socket

3. Some ports have no socket, e.g, audio or onboard hub. Some are board headers

4. Port ID assignment requires setting the proper port type #, which varies per point 3. You'll have to read guide as I can't recall off top of my head.

THIS APPROACH OBVIATES USBInjectAll and its lore/pitfalls.
*** Get rid of USBInjectAll unless you know you need it.

You have to play with this a little to learn/find your layout, so make a diagram to guide your work. Later it's not hard to update / change because your board doesn't change.

I use this with OpenCore on my kit and it works well.

Hello there.

Thanks for your input. Normally this would be classed as an "off topic" post and removed, as it doesn't add to this particular technique for helping beginners configure their USB ports. However keeping it and replying will be helpful to others.

Firstly I need to say that I have no problem with CorpNewt's python script, or any of their other very useful releases. If you would prefer to use those tools then please do. There is nothing compulsory in the Hackintosh world.

Okay, let's dive in:

If any of the language in the guide is "overly narrow" it is only to help people with limited knowledge get a grasp on what they need to do to get the job done.

You say: "There clearly is support for more than 15 ports, or expansion hubs would make no sense on Mac."

Well this is misleading. A hub connects to a single motherboard port - one of the 15 Apple allows. It's true you can daisy-chain USB hubs, all from a single designated USB Port, and macOS will recognise them. Any operating system would. That is a fundamental fact about USB. However, Apple only designated a 15-port stack for their hardware and this is what we are trying to emulate to allow macOS to run on our PCs.

Your description of how the USBMap script produces a USBMap.kext is fine. And the process for creating a USBPorts.kext using Hackintool is very similar. I'm sure you have done this already, but compare the XML code of a USBMap.kext with that of USBPorts.kext. Every picture tells a story as they say.

USBInjectAll was written long before either of my guides or CorpNewt's script. Its author added a lot of other useful functionality besides just the initial mapping process, but you can do everything without USBInjectAll.kext if you really have a valid objection to doing so. You can also do everything without the USBMap script too. To configure your ports this way just dump the DSDT files locally using your bootloader, find the USB stack configuration file and manually edit this to your desired map. Patch it back in during boot and there's no need for any kexts or add-ons at all. But ... this is hardly a method for beginners.

I'm glad to hear your own system works well.

 

[10tacle]

Thanks for all the info guys, I’m on vacation and I’ll get back to it in a couple of days.

 

[SergeNu]

Hi guys!

I have a problem with detecting USB 3.0 SS ports, all HS ports mapped correctly, but no one detected as SS with USB 3.0 stick.

Screenshot after Dornania USB map guide.

Any suggestions?

SOLVED.

 

[tortuga343]

Hi guys!

I have a problem with detecting USB 3.0 SS ports, all HS ports mapped correctly, but no one detected as SS with USB 3.0 stick.

Screenshot after Dornania USB map guide.

Any suggestions?

SOLVED.

how do u solved this? i have the same problem. on usb 3.0 port will not be recognized usb 3.0 sticks only 2.0.

 

[Edhawk]

@SergeNu You are only seeing the first 15 ports because you don't/didn't have the correct USB port limit patches in place when undertaking the USB port discovery.

You should look at using SSDT-EHCx-OFF.aml (attached below) to disable the EHxx ports, as these are covered by the HSxx ports (i.e duplicated). It is how I have my 9-series USB ports configured.

 

[Edhawk]

@tortuga343 your Z370 system is completely different to SergeNu's 8-series system.

You have two USB controllers in your system, an ASMEDIA 2142 controller and an Intel 200/Z370 controller. These two controllers need to be dealt with in a different manner.

USB ports for Asus ROG STRIX Z370-G Gaming MB.

ASMEDIA USB ports:
The Asmedia PXSX controller's 4 ports should all be retained and included in your USBPorts.kext, as they do not exceed the 15 port limit.

You have set two of the ports PRT3 and PRT4 as USB2, this is incorrect. They should all be set with the USB3 connector type.

INTEL USB ports:
The XHC Intel ports need to be reduced to a maximum of 15 ports. 21 of the 22 USB ports available on your motherboard are showing, so you probably have the correct USB port limit patches in place, or are using OC's XhciPortLimit quirk.

HS08 is not showing and I assume you have inadvertently/purposely deleted this port. You need to Clear and Refresh the Hackintool USB Window, using the Sweeping broom and then the Circular Arrow icons, in that order for all 22 XHC ports to be displayed.

What you have not understood is that any USB2 port served by/from a Physical USB3 port or motherboard header needs to be set with the Connector type USB3, not USB2. While this may seem incorrect it is the physical ports attributes that dictate which connector type should be used for any given port, whether that is a Virtual USB2 or physical USB3 port.

You should only have two ports set as USB2, the two ports identified below under Rear panel connector #3

Rear I/O plate connectors.

Your Hackintool screenshot is showing 5 x 'Internal' USB ports, this is again incorrect. As your motherboard only has two USB2 internal header ports, which provide 4 x USB2 ports. So you should have a maximum of 4 x USB ports set with the 'Internal' connector type, assuming all 4 ports are being used.

The USB3 Header ports should not be tagged as 'Internal' but rather as USB3, this header provides 4 x USB ports (2 x USB3 physical and 2 x USB2 virtual ports). All four ports need to be given the USB3 connector type.

I am assuming that if you had HS08 visible on the screenshot you would have this set with the 'Internal' connector type.

Fix the issues mentioned above and see where that gets you. We can revisit the setup/configuration once you have remedied these issues.

What you might want to do is use the 'Comment' column to identify which port is associated with each physical or Header port in your system. An example of this is shown below.

Hackintool screenshot showing Comments for each USB port.