One of my ports is not listed.

[joevt]

In the list of ports, I don't see HS01 even though it exists in the IORegistry.

I'm using Clover and am in the process of converting to OpenCore. For Clover, I'm using USBInjectAll.kext but I want to switch to USBMap.kext. My Clover boot-args is this: -v dart=0 nvda_drv=1 nv_spanmodepolicy=1 keepsyms=1 debug=0x14e -lilubeta -liludbg -alcbeta -alcdbg -igfxdbg -ngfxdbg uia_exclude=HS03;HS07;HS08;HS09;HS10;HS13;HS14;USR1;USR2;SS03;SS07;SS08;SS09;SS10

HS01/SS01 are the upstream of a USB 3.0 hub on the motherboard which has two USB 3.0 connectors for four USB type A ports on the front of my computer case. All four ports currently work with both USB 2.0 and USB 3.0 devices.

I've attached the ioreg for all my USB controllers (chipset, Alpine Ridge, ASM1142). Should the USBMap.kext include info for the Alpine Ridge (built into the Z170X-Gaming 7 motherboard) or the ASM1142 (in a PCIe x4 slot)?

ioreg_usb.txt.zip

[joevt]

Question: In the "Discover Ports" menu, SS01 has type 255, but in the "Edit & Create USBMap.kext" menu, it has type 3. Why is that? Should it be 255 since it's the upstream source of an internal USB 3.0 hub?

Since the USB map matches by PCI bus number, I'll probably not choose to include Alpine Ridge in the map since the USB controller of the Alpine Ridge will have a PCI bus number that's related to the number of buses used by other previously enumerated PCI devices which might not always be constant (for example, if I remove my FireWire card). Isn't there a ioregistry path match that could be used instead?

Another issue: I created the kexts, and found that HS01 was included but has the same comment as SS09 but that comment is from HS05/SS05 in the "Edit & Create USBMap.kext" UI. The comment for HS06/SS06 was saved to HS02/SS10... etc. I've attached the generated kexts and the "Backup Detected Port Plist" to compare.

Results.zip

[joevt]

Regarding match by PCI bus number (pcidebug property), the guide at https://dortania.github.io/OpenCore-Post-Install/usb/manual/manual.html#iopathmatch says there's match by path option. I think that should be used instead of match by property.

[joevt]

Regarding the comments not matching, it appears that it may be normal behaviour - that USBMap renames the ports so that HS05 in the "Discover Ports" menu is renamed as HS01 in the USBMap.kext? It's confusing though. I prefer the SS and HS numbers to match each other for a single USB 3.0 port, and also for the number in the name to match the port number.

[corpnewt]

Hey there - can you send a complete ioreg dump using ioreg -lw0 > ~/Desktop/ioreg.txt ?

Should the USBMap.kext include info for the Alpine Ridge (built into the Z170X-Gaming 7 motherboard) or the ASM1142 (in a PCIe x4 slot)?

Yes, USBMap can map third party controllers as well as chipset controllers.

In the "Discover Ports" menu, SS01 has type 255, but in the "Edit & Create USBMap.kext" menu, it has type 3. Why is that? Should it be 255 since it's the upstream source of an internal USB 3.0 hub?

I'll have to revisit the code to verify, but I believe I had it default based on the controller type, as often information provided by ACPI is incorrect. If that's not the case for the majority of users, I can look into forwarding that info as it is gleaned when populating controllers.

Isn't there a ioregistry path match that could be used instead?

I moved away from IOService path matching as it wasn't consistent between reboots for my 2 ASMedia controllers - causing them to use each others' maps seemingly at random. The current matching approach has been significantly more consistent in broad use, but you are correct in that hardware changes can be reflected in the ioreg and possibly cause mismatching.

I prefer the SS and HS numbers to match each other for a single USB 3.0 port, and also for the number in the name to match the port number.

You can manually edit the port names after building the kext if you like. USBMap names them in ascending order by type (HSxx/SSxx) for convenience. Your SSxx ports won't match the port number though, as they don't start enumerating at port 1. In your screenshot above, your SS01 port is at 17 (0x11). Since the script is intended to be used on all manner of machines, I figured it sane enough to just increment by type.

Please let me know if I missed anything or if you have other questions. I hope that helps!

-CorpNewt

[joevt]

My original issue was that HS01 doesn't appear in the UI - To be more precise, port 14100000

I'm currently running Catalina with OpenCore and a manually created USBMap.kext. USBMap.command still doesn't show 14100000 and it doesn't show DP03 and DP04. I'm not sure how to setup these 4 hub ports. The USB 3.0 part of the hub appears to have not been enumerated by macOS (it should exist under 14a00000). Should I not be using 255 for the upstream of an internal USB hub?

ioregjoevtCatalinaAndUSBMap.zip

[corpnewt]

Hmm - I see what you mean. I found the issue in the script, but so far my attempts to fix it have broken other things. Worst-case, I'm in for another rewrite of the core logic. Best-case I can patch in support.

I'll keep you posted. Thank you for bringing this to my attention 👍

-CorpNewt

[corpnewt]

I just pushed a commit that should hopefully solve this issue here. Please let me know if you continue to have troubles and I'll reopen this issue.

I also added some QOL things you had suggested, namely that the script will respect detected connector types unless overridden, and the option to toggle between IOParentMatch and IOPathMatch in the resulting kexts.

Hopefully that helps 👍

-CorpNewt

[joevt]

Thanks. I think it's working better now, I can see HS01 and it's not including hub ports, but it won't add HS10 (port 0x0a) to the kext even if I enable it. Ports that are not enabled have #port key instead of port in the Info.plist. The kext includes HS01 to HS09 and SS01 to SS06 - I enabled just a couple of those to see what would be produced in the kext.

I see the script doesn't show ports that don't exist in the ioreg. For example, HS02 (port 2) which I have disabled. But it does include the port as a disabled port in the Info.plist (and somehow it knows the port is named HS02? Or it extrapolates the name from the port number? Or more likely it comes from the map that's already in the IORegistry (the ports property of the USB controller's IORegistryEntry)?)

I'll try setting SS01 to Type 3 instead of Type 255 and see if it enables the USB 3.0 part of the internal hub.

[corpnewt]

I leveraged your ioreg, reset any USB ports detected (via R at the main menu), went into discovery to populate the controllers/personalities, then went to edit the plist. I then selected all ports via A, and build the USBMap kext via K, and this was the final result before building the kext:

The naming convention for port personalities in that list are based on what they were last seen called in the discovery page. We can see that it skips HS02, as you do not have that present in your ioreg. HS10 is enabled, and at addres 0x0a as you've noticed as well. When USBMap builds the kext - it numbers them based on the discovered port personalities. Since HS02 does not exist in your ioreg, this current instance of USBMap has never discovered it, and does not know it exists. As such - it is not considered when naming the ports for the built kext.

USBMap will iterate through the list naming things as follows with the discovered name (Old) at the left, and the name in the kext (New) at the right:

Old     New
------------
HS01 -> HS01
HS03 -> HS02
HS04 -> HS03
HS05 -> HS04
HS06 -> HS05
HS07 -> HS06
HS08 -> HS07
HS09 -> HS08
HS10 -> HS09
SS01 -> SS01
SS02 -> SS02
SS03 -> SS03
SS04 -> SS04
SS05 -> SS05
SS06 -> SS06

We can notice two things in the above list; 1) HS03 through HS10 are shifted down one number because the script is unaware that HS02 ever existed (as it was never discovered), 2) the SSxx port names do not change - this is because all AppleUSB30XHCIPorts were discovered, and none were skipped.

If we look at the final map - and consider the port address instead of names (as the names are entirely arbitrary and can be any 4 digit combo - the USBMap dummy injector uses the UKxx format, as the ports are unknown with that injected info), we can see that port 0x0a does in fact exist. It has just had its name changed from HS10 in the original mapping to HS09 due to the missed HS02:

A large part of the reason USBMap doesn't just take the existing name is that many firmware devs don't follow any naming conventions for port personalities. It's also worth noting that when using the USBMap dummy injector - all ports will be named with a UKxx format - which also isn't terribly helpful in a final map. If all port personalities were discovered, the naming conventions should line up properly though.

Hopefullly that clears things up - please let me know if you have other questions/concerns.

-CorpNewt

[joevt]

Thanks for the explanation. I think I got confused again by the renumbering/renaming. Port 10 (0x0a) is in the generated Info.plist as HS09 as you say.

I guess there should be more emphasis on the fact that the names in the map will not necessarily be the same as the names in the ioreg or the UI.

I am stuck in the mindset of using the names created by USBInjectAll.kext that I'm replacing. I have therefore renamed the names in the Info.plist created by USBMap to match those names. So the reason for the mismatched names is because my USBMap that is currently in use skips the HS02 name (which I reserve for the disabled port 0x02).

Also, I was able to get the USB 3.0 hub to work by setting port 0x11 to type 3. I set port 0x01 to type 3 as well to match.