MSI Z690I Unify usb ports mapping

[badformat]

Use Corpnewt's USBmap and skip USBInjectAll and XhciPorrLimit quirk.

You'll need to put a python on your system to run it but these are readily available.

The documentation is sparse but what you need to know is there.

Read the quick-start and play with the script and it will make sense.

Outline:

0. Remove all config pertaining to port mapping. Attach only bare minimum USB to operate system. Have devices handy for each connector type and USB 2 / USB 3, as appropriate. A USB 3 hub can be handy because it can be both personalities, but a mouse dongle and USB 3 flash drive will serve.

1. Run USBmap to Discover root controllers, generate a "dummy" kext and boot it

2. Discover ports. If a root controller has more than 26, poke around to find some to eliminate and use the alternate support script to pare down dummy to be able to see the ports you need (disable ports in dummy, replace dummy and reboot).

3. Detect all needed ports, disable unneeded ports to get down to 15 max (directly connected to root) and set connector types for active ports.

• You decide the tradeoffs / mix of active ports.

• As many other ports as you need can branch from these 15, mapping only pertains to ports directly connected to the root.

• If you have more than one root, each root gets 26 (during discover) / 15 (final).

• Connector type is determined by the final wiring to reach the downstream device, so a header that connects to a case harness with a type-A port is typically 3, while a header connected to a bluetooth adapter is 255 (internal). USBmap has a list built in to remind you. Late model type-C ports are 9 (switched)

4. Generate the final USBmap.kext and replace dummy with it.

• You can return to make adjustments.

If you change SMBIOS you need to revisit the layout. Ports may or may not stay the same, and at a minimum the SMBIOS label written into the kext must be updated if you change SMBIOS for your build.

Live long and prosper

Thanks for your guide c-o-pr

but maybe I'm doing something wrong.

1) I removed all my usb kexts I created before. Rebooted.

2) Ran USBmap, discovered ports. (for some reason it discovered only 15 my XhciPortLimit quirk is set to False)

3) Created a Dummy kext and set it up

4) After this I ran USBmap and tried to discover ports, here is what I saw:

5) I started to plug in USB 3.0 flash drive and it wasn't recognised in any port. Only USB 2.0 flash drive are working.

First of all I just don't understand why I see limited number of ports since I have quirk disabled and I don't have any .aml or .kext for usb.

I'll continue to research.

 

[UtterDisbelief]

Thanks for your guide c-o-pr

Tbut maybe I'm doing something wrong.

1) I removed all my usb kexts I created before. Rebooted.

2) Ran USBmap, discovered ports. (for some reason it discovered only 15 my XhciPortLimit quirk is set to False)

View attachment 552319

View attachment 552318

3) Created a Dummy kext and set it up

4) After this I ran USBmap and tried to discover ports, here is what I saw:

View attachment 552320

5) I started to plug in USB 3.0 flash drive and it wasn't recognised in any port. Only USB 2.0 flash drive are working.

First of all I just don't understand why I see limited number of ports since I have quirk disabled and I don't have any .aml or .kext for usb.

I'll continue to research.

By default macOS only shows 15x ports as that is its native limit. The reason we use a port-limit removal patch or quirk is to open up all available Intel chipset ports.

Since Big Sur 11.3 this has become problematic.

Hopefully @c-o-pr can jump in to show how you can see more ports and go forward.

If you are not able to boot a version of macOS prior to BS 11.3 and create a fully working kext using the XhciPortLimit quirk, it is possible to get the job done using a sys-def compatible version of USBInjectAll and its "exclude" ports option.

 

[c-o-pr]

Thanks for your guide c-o-pr

but maybe I'm doing something wrong.

1) I removed all my usb kexts I created before. Rebooted.

2) Ran USBmap, discovered ports. (for some reason it discovered only 15 my XhciPortLimit quirk is set to False)

View attachment 552319

View attachment 552318

3) Created a Dummy kext and set it up

4) After this I ran USBmap and tried to discover ports, here is what I saw:

View attachment 552320

5) I started to plug in USB 3.0 flash drive and it wasn't recognised in any port. Only USB 2.0 flash drive are working.

First of all I just don't understand why I see limited number of ports since I have quirk disabled and I don't have any .aml or .kext for usb.

I'll continue to research.

The dummy is supposed to take the place of inject all and limit, so I'll have to think about what's going on...

I've used it recently under monterey and didn't run into the problem

Any chance the dummy is not actually enabled?

Did you run "discover" for at least one 5 second cycle before generating dummy?

 

[badformat]

The dummy is supposed to take the place of inject all and limit, so I'll have to think about what's going on...

I've used it recently under monterey and didn't run into the problem

Any chance the dummy is not actually enabled?

Did you run "discover" for at least one 5 second cycle before generating dummy?

Dummy is enabled because ports now called UK.

I guess that Monterey has 15 ports limit and that's why it doesn't show everything.

I checked .plist inside dummy kext and there a lot of UK ports, more than 15.

I guess that one of the way is to try uia_exclude boot arg to see them all. But the thing I don't like is that in this first list no USB 3 ports at all.

EDIT: checked uia_exclude arg doesn't work for UK name

 

[UtterDisbelief]

... to try uia_exclude boot arg to see them all. But the thing I don't like is that in this first list no USB 3 ports at all.

EDIT: checked uia_exclude arg doesn't work for UK name

That's actually on the ball. You use the "exclude" command with USBInjectAll to ignore the USB2 ports and only USB3 shows up. And vice-versa.

I haven't seen UK** used before. You could always dump the DSDT using Hackintool and look for the USB-specific aml file. Usually around no. 5 or 6. And check to see what the port names in there are. If still UK well that's a first!

 

[c-o-pr]

Dummy is enabled because ports now called UK.

I guess that Monterey has 15 ports limit and that's why it doesn't show everything.

I checked .plist inside dummy kext and there a lot of UK ports, more than 15.

I guess that one of the way is to try uia_exclude boot arg to see them all. But the thing I don't like is that in this first list no USB 3 ports at all.

View attachment 552328

EDIT: checked uia_exclude arg doesn't work for UK name

So use the other script to disable ports to bring ones you want into view. IOW you are just starting with 15 max rather than 26 but the chore is the same. You are going to end up with 15 anyway and you clearly don't expect to use most of the ones listed, so disable them and continue.

I anticipate there's still some config left over in your build from other efforts contributing to the effects you see, but I guess this only for lack of a better explanation

 

[c-o-pr]

Addtl thoughts: Maybe the script got tweaked to only display 15 to avoid other confusion?

I think there was a originally a distinction between the InjectorEdit script and USBmap script that is about how the tool evolved: the InjectorEdit version is just a quickie in-place editor for a map. In the beginning a map is "all enabled all unknown (UK)" and only edits it permits are enable/disable.

The USBmap script is where the work gets done and it seems to have a memory beyond the map at hand, which is why there's a "reset" command...

My point is that this feels like a tool that came together from experiments, not designed from top-down, so you have to warm up to it and it has some quirks (in true sense).

 

[Edhawk]

Using the following information may help you with the USB port discovery phase.

USB ports on your MSI motherboard.

• 1x USB3.2 Gen2x2 20Gbps port (1 Type-C internal connector)
• 2x USB 3.2 Gen 2 10Gbps ports on the back panel
• 6x USB 3.2 Gen 1 5Gbps ports( (4 Type-A ports on the back panel and 2 ports available through internal USB connectors)
• 2x USB 2.0 ports available through the internal USB connector

Here are two screenshots showing the back panel and motherboard.

Back Panel (I/O plate)

Motherboard layout with Header ports highlighted.

Your motherboard has a maximum of 21 USB ports on the XHC controller (excluding the TB ports).

• 12 ports from the 6 x USB3 on the back plate, all set as USB3 (3)
• 2 ports from the 1 x USB2 header, if used these need to be set as 'Internal' (255)
• 4 ports from the 1 x USB3 header, if used these need to be set as USB3 (3)
• 2 ports from the 1 x Type-C header, you need to undertake the Type-c flip test to see if these are type (9) or (10).
• 1 port from the built-in WiFi/BT M.2 connector, this should be set as 'Internal' (255).
  • This port shows as UK14 (HS14) in the Hackintool screenshot you provided in post #15.

From the Hackintool screenshot you provided I would say the 6 x USB2 (virtual) ports on there back panel are ports UK01 - UK06 inclusive.

One thing I have noted is your USB controller is named XHCI. This is usually renamed to XHC_ in the OC config.plist, to prevent it clashing with the Apple USB controllers. This is something you need to deal with and add to your config.plist, before you get any further in to the USB port discovery phase.

The ACPI rename patch looks like this in ProperTree.

XHCI to XHC_ rename patch

 

[c-o-pr]

@Edhawk: In my z590 build (stable) the controller is also named XHCI with no rename. But I've had no prob with discovery.

I've never came upon the rename observation until your post above. Can you say a bit more about what the conflict is about?

My system has had some occasional odd behaviors, and I assume USB config could cause almost any kind of glitch. But it's also in daily heavy use, and generally working fine with USB doing everything I expect and need it to do.

 

[Edhawk]

Going back a way, i.e. when El Capitan was released, it was known that specific USB controller names were used by Apple. EHC1, EHC2, XHC1 and XHCI being the main names by Apple. Apple also introduced the 15 port limit at this time.

To avoid the Hackintosh USB controllers clashing with the Apple controllers, by using the same device names and having more than 15 ports available. ACPI rename patches were provided for these USB devices (and other devices).

These renames were used prior to El Capitan but more commonly within DSDT.aml patching.

The use of these ACPI rename patches was well documented when using Chimera/Chameleon (DSDT) & Clover within the config.plist.

The System Preparation section of the OpenCore setup/guide contains three ACPi rename patches, see the link below. It is a section of the guide which most people don't bother reading. Otherwise the use of the patches would probably be more common.

System Preparation | OpenCore Post-Install

On older systems, Ivy Bridge, Haswell & Broadwell systems, EHC1 and EHC2 are present as well as XHCI controllers. Sandy Bridge systems use different USB names. As do some mixed 6-series/7-series systems.

• Dortania recommend using SSDT-EHCx-Off.aml to shunt the EHC1 & EHC2 ports to the XHC controller for these older systems.
• If the SSDT is used, then the EHC1 to EH01 and EHC2 to EH02 rename patches are not required.

Skylake and newer Desktop systems usually only have the XHCI controller. Some have the Thunderbolt USB controller (XHC5), but as there are only 4 ports on the TB USB controller they don't cause any issues.

Once the system has a USB injector kext (USBPorts.kext etc.) the Skylake & newer rename patch is supposedly not required. I don't know why that would be the case, as surely the injector kext would be looking for the renamed USB controller, not the old name! Remove the rename patch and the USB controller would revert to its original ACPI name.

The System Prep guide says a number of systems DO NOT require these patches. I assume you and @badformat have systems that don't require the rename patches. Theoretically that is!

• iMac18,x and newer
• MacPro7,1 and newer
• Macmini8,1 and newer
• MacBook9,x and newer
• MacBookAir8,x and newer
• MacBookPro13,x and newer

I don't know why they wouldn't need to use the rename patches, if they have the XHCI or XHC1 USB controller. As the same clashes could still occur.

Hope this helps.