The New Beginner's Guide to USB Port Configuration

[Edhawk]

Also Dortania don’t provide a link to an SSDT-PM.aml. This is something you have to generate yourself, for your specific system.

SSDT-PLUG.aml doesn’t work on an Ivy Bridge system.

 

[bobm]

Four of the USB3 ports on the rear I/O plate are not Intel USB ports. They a VIA USB ports, so might need something extra to work in macOS. Did you use any additional/third-party kexts in earlier versions of macOS? USBInjectAll.kext won’t work with the VIA USB ports.

If you are using OpenCore to boot your system the XhciPortLimit quirk no longer works in Big Sur 11.3+. You may need to install Catalina or an earlier version of macOS to undertake the USB port discovery, where the USB port limit patch does work.

Thanks for the clarification. I have been distracted for several days, having moved RAM and BCM card from this Z77X board to a different machine, but frustrated by multiple problems getting that install to work, have decided to go back to the Z77X and resolve the USB issues.

Fact is, if I get my BT working on the big sur/Z77X machine, I can use BT mouse/trackpad/kbd, so I would have 4 Intel physical USB ports working, probably enough for my use-case (music DAW, just need 1 USB for hi-end audio DAC, and 1 for occasional external HDD or other misc use)

Is the VIA USB port issue on my Z77X something that can be resolved with a DSDT/SSDT solution? I may add a Linux boot along side the Big Sur on this board, so maybe working there initially I can more easily get a custom DSDT/SSDT done, then use this to boot macOS. Would you recommend going in this direction.

 

[Edhawk]

What I would recommend is as follows:

1. Install macOS Catalina 10.15.7 on your Z77 system using OpenCore.
2. Undertake the USB port Configuration as set out in this guide - https://www.tonymacx86.com/threads/the-new-beginners-guide-to-usb-port-configuration.286553/
3. This will allow you to use the XhciPortLimit quirk and undertake the USB port discovery for the Intel USB ports.
4. The XhciPortLimit quirk stopped working in Big Sur 11.3 and any newer versions of macOS, so an early release of Big Sur or Catalina is required for the port discovery.
5. Once you have your USBPorts.kext for your system, it will work in Big Sur and Monterey, or any earlier versions of macOS going back to El Capitan.
6. Don't worry about the Via USB ports, if they don't show up in Hackintool.

Regarding the use of SSDT's for your system I would recommend using Corpnewt's SSDTTime to create the following SSDT's, using your unpatched DSDT.aml as the base.

• SSDT-HPET.aml - IRQ conflict fix
• SSDT-EC.aml - EC fix
• SSDT-USB-Reset.aml - Forces USB ports to reset and makes port discovery easier to manage.

Along with SSDT-HPET.aml SSDTTime will generate 2 or 3 ACPI > Patches, which you would need to add to your config.plist in order for the SSDT-HPET.aml to work correctly.

You don't need the other SSDT's available from SSDTTime script, as your Ivy Bridge system can't and doesn't need to use them.

Depending on the SMBIOS you are using you may also need to add SSDT-USBX.aml to your setup, so you have USB power regulated. This pre-compiled SSDT can be downloaded from the link below.

OpenCore-Post-Install/extra-files/SSDT-USBX.aml at master · dortania/OpenCore-Post-Install

https://dortania.github.io/OpenCore-Post-Install/. Contribute to dortania/OpenCore-Post-Install development by creating an account on GitHub.

github.com

 

[bobm]

What I would recommend is as follows:

Good plan, thanks, I will go this route.

But first still struggling to get past Step 1, Install Catalina. Spent many tedious hours today moving my install USB back and forth from MacBook where I configure OC and createinstallmedia, to the Z97X machine I am trying to Hack up.

I don't want to go too far off the USB port-mapping topic, but I can boot into OC's picker no problem, but can't get the install macOS catalina to show up in the picker. I've checked and rechecked the file structure on USB main partition and EFI countless times, I've got scan policy at 0, and in UEFIShell I can see that HfsPlus.efi is loading OK. Have tried every possible OC config tweak which might be causing the problem, but so far NG. Next step will be to go out and pick up a USB flash drive of a different brand - I've been using a Silicon Power 64Gb stick. If that doesn't do it, I'll open a separate thread to seek assistance.

Don't worry about the Via USB ports, if they don't show up in Hackintool.

not sure what you meant here. will the Hackintool port config process somehow get the Via-connected physical ports working even if they don't show, or should I just learn to live without these ports? (the Via chip runs 4 out of the 8 physical ports on this box, not counting 3 inside on the board itself).

Finally, let me know if you think there's any possibility that my install problems might be resolved with bespoke SSDTs, I might just go ahead and install a Linux image temporarily, and do Corpnewt's SSDTTime thing from linux if I can't get macOS working first.

 

[competetowin]

Install Catalina.

I've had success mapping following some of open core's instructions, and using the USBMap tool.
Personally, I found the USBMap's Quick Start (readme on github) confusing. OpenCore's outdated instructions are clearer to follow, but they haven't been updated to account for USBMap tool no longer requiring USBInjectAll.kext nor the XhciPortLimit quirk. So just ignore those steps in the System Preparation section and you should be able to follow along.

 

[c-o-pr]

Personally, I found the USBMap's Quick Start (readme on github) confusing.

Yes I agree the Quick Start is missing important context for understanding its use.

I just went through a session of relearning how it works and made additional notes, which I'll review and post.

Key things that every user needs to know but are not spelled out:

1) The working memory of the tool is kept within the Info.plist of the tool's output in Results/USBmal.kext. You can inspect it with a property list editor, by showing package contents.

2) Due to "companion ports" (HS vs SS) showing up as separate list entries, and also due to the spread of these entries across the range, your board may have more ports to select from than will fit into the absolute list maximum of 26. So you have to detect ports in stages, where you
- start clean with no Results/USBmsp.kext and (R)eset — delete existing if needed.
- (D)etect just so the tool can make an unpopulated list of controllers — you don't need to activate every port as the Quick Start suggests; I think QS step about this is a typo
- (K) generate a Dummy USBmap.kext,
- install into EFI and boot with it,
- (D)etect to discover what ports you are surely NOT going to need,
- quit USBmap
- run the Edit script to disable ports you DO NOT need to create room in the list of 26 — the edit script updates the Info.plist within the Dummy in Results/USBmap.kext,
- install the pared-down dummy and
- reboot again,
- (D)etect again to locate the ports you DO you need that didn't show up on the first go-around, and
- (P) finalize your choices according to the 15 per controller macOS limit and assign port types to get an optimal USBmap.kext for your purposes.

3) You don't need USBInjectAll, nor OC/Kernel/Quirks/XhciPortLimit; don't use these.

4) If you have an error in your OC kext startup and Lilu is not first where it belongs, controller naming may be affected which adds to confusion. Be sure your base OC config is solid before attempting USB mapping.

There are some other tidbits I'll post later, but the above is the gist.

 

[competetowin]

@c-o-pr much clearer! I wanted to propose a rewrite to dortania's team, but it should be you to do the push request. You seem to understand this really well. I would suggest you place your 3) step somewhere near the top, as OC's content specifically tells users to use them in a previous step.

Unrelated to mapping, but since you brought it up:

Lilu is not first where it belongs,

Does it have to be first in all circumstances? My boot is taking ages longer now than with previous OS. I don't remember what it was then, but now I know I have IntelMausi loading first. I wonder if that's a mistake. I'm letting Proper Tree create the snapshot. (Also, I don't know if I even need it, as my ethernet chip is TexasInstruments)

 

[c-o-pr]

@c-o-pr much clearer! I wanted to propose a rewrite to dortania's team, but it should be you to do the push request. You seem to understand this really well. I would suggest you place your 3) step somewhere near the top, as OC's content specifically tells users to use them in a previous step.

Unrelated to mapping, but since you brought it up:

Does it have to be first in all circumstances? My boot is taking ages longer now than with previous OS. I don't remember what it was then, but now I know I have IntelMausi loading first. I wonder if that's a mistake. I'm letting Proper Tree create the snapshot. (Also, I don't know if I even need it, as my ethernet chip is TexasInstruments)

I wasn't planning to push towards Dortania, just because I'm lazy. My view is limited to the effects I can see, not true understanding of how this stuff works.

For example, I'm writing from POV of Monterey. it's prolly the case that some users of some systems need the Quirk — idk. Others pls clarify

I believe that USBmap succeeds USBInjectAll. IOW it's a newer easier way of doing what used to be done with USBInjectAll.

There are many finer points I feel need coverage in a good write-up and lore gets old rapidly

Re Lilu, the rule about it coming first is that it provides some default operating config and some primitive operations which are commonly used by other kexts. That's its reason for being, so by definition it should be loaded before everything else.

The only reason I know for boot delays is NVMe Trim pathology.

I'm a latecomer to all this and happy to explain what I've seen, but compared to the many veterans here, I'm at a loss on most details, so on this topic I have to leave it for others. .

Best to you

 

[UtterDisbelief]

Yes I agree the Quick Start is missing important context for understanding its use.

I just went through a session of relearning how it works and made additional notes, which I'll review and post.

Key things that every user needs to know but are not spelled out:

1) The working memory of the tool is kept within the Info.plist of the tool's output in Results/USBmal.kext. You can inspect it with a property list editor, by showing package contents.

2) Due to "companion ports" (HS vs SS) showing up as separate list entries, and also due to the spread of these entries across the range, your board may have more ports to select from than will fit into the absolute list maximum of 26. So you have to detect ports in stages, where you
- start clean with no Results/USBmsp.kext and (R)eset — delete existing if needed.
- (D)etect just so the tool can make an unpopulated list of controllers — you don't need to activate every port as the Quick Start suggests; I think QS step about this is a typo
- (K) generate a Dummy USBmap.kext,
- install into EFI and boot with it,
- (D)etect to discover what ports you are surely NOT going to need,
- quit USBmap
- run the Edit script to disable ports you DO NOT need to create room in the list of 26 — the edit script updates the Info.plist within the Dummy in Results/USBmap.kext,
- install the pared-down dummy and
- reboot again,
- (D)etect again to locate the ports you DO you need that didn't show up on the first go-around, and
- (P) finalize your choices according to the 15 per controller macOS limit and assign port types to get an optimal USBmap.kext for your purposes.

3) You don't need USBInjectAll, nor OC/Kernel/Quirks/XhciPortLimit; don't use these.

4) If you have an error in your OC kext startup and Lilu is not first where it belongs, controller naming may be affected which adds to confusion. Be sure your base OC config is solid before attempting USB mapping.

There are some other tidbits I'll post later, but the above is the gist.

It would be great if someone wrote a Guide for USBMap or USBToolBox here. Personally, I don't plan to because re-inventing the wheel doesn't appeal to me. I suspect a majority enjoy the visual paradigm Hackintool presents.

Worth noting is that there are just three ways to configure USB ports - using USBInjectAll, by dummy kext injection or direct ACPI patching. Someone may write a comparable alternative to the code in USBInjectAll, but it's pretty comprehensive, under the skin, and I haven't seen anyone match it yet. I have great respect for the work of @RehabMan. Later versions than 0.7.1 have been editied by other people to include newer system-definitions, that's all.

Apart from Hackintool, USBMap and USBToolBox the other way to configure USB ports is by directly patching the DSDT table at boot. This just requires dumping the system's DSDT, finding the SSDT that controls USB, manually editing it and then merging it back in. @MacMan covered this very well for an ASUS set up using Clover and I've used the technique now both with Gigabyte and more recently ASUS, using OpenCore, for my latest project. This is configuration in it's purest form but perhaps a bit too raw for most people - and what's more does not rely on an initial port-limit removal technique, as long as the coder knows which ports are which.

 

[swytch]

I orig followed this guide a couple years ago to get my usb ports mapped after installing Mojave. now, looking at my available usb ports in Hackintool or IORegistryExplorer there are extra ones (ones not mapped in USBPorts.kext), causing my USB3 ports to not work (past 15 limit - only 1 USB3 port now shows in IORegistryExplorer, all show in Hackintool but when usb3 drive plugged in it won't load). in Hackintool, the extra ports show as inactive (not highlighted in green)

I tried overwriting USBPorts.kext with a backup from when i orig sort them up, I also tried deleting the incorrect ports in Hackintool getting the list down 2 to 15 again, and creating a new USBPorts.kext and installing it in clover.

i also tried rebuilding kext cache (sudo kextcache -i /)

can anyone help?