Usb on A+ programming moments

How-to: USB mapping for OpenCore

Sun, 09 Feb 2020 04:42:00 +0000

With the problem of USB mapping explained in the previous article, now we need to see how to workaround it. The ultimate goal is to have all the available ports that we want working, as both USB 2.0/3.0.

There are some interesting articles on this topic:

USB Map by CorpNewt, useful for historical perspective and Intel-based machines.
The New Beginner’s Guide to USB Port Configuration, uses Hackintool which lists active port configuration in its USB tab. I found its display to be confusing and incorrect. Probably works OK for Intel machines.
AMD USB Map part of OpenCore Vanilla Desktop Guide, which is the only one related to AMD stuff but also way too terse.

General rule for AMD builds: ignore any guide that tells you to use USBInjectAll kext and/or USBMap tool. They were made for Intel-based builds and do not work with AMD chipsets, at all.

Remember:

OpenCore is not altering macOS in any way. Which means no kexts are placed inside /System/Library/Extensions.
OpenCore kexts are loaded before macOS loads its own.
Thus .kext applied by macOS can’t be overridden.

So in my case, I can’t override iMacPro1,1-XHC1 mapping from previous article. Whatever I do, macOS will apply that map and hide my ports 1 and 9. XHC1 string is used in two places:

in the key itself: iMacPro1,1-XHC1
as the value of the IONameMatch key

Thus the only course of action is to rename that controller so Apple’s map – which is based on “XHC1” value in the IONameMatch – has no physical ports to work with.¹

That brings me to another problem. Since the .kext mapping is based on such a simple string name, I can’t use XHC0 for two different controllers – I need to rename one of them into something else.

Hence, will remap XHC1 into XHCI and also rename second XHC0 (under GP13) into XHC2. This will be done using two custom SSDT files:

I created these two files following the samples available in the Vanilla desktop guide.² I lack the knowledge to write these from scratch and I’m grateful those samples are available.

With those two files added into config.plist, all of my ports were working and I did not need to create any .kexts because all 3 controllers have less than 15 ports (10, 10 and 8).

So, job done, for me, without actually doing any port mapping, at all. When do you need a specific map?

Port mapping means that you know exactly which physical port maps into which logical software port, both for USB 2.0 and 3.0 paths.

This is fairly easy to do, with one caveat: what if your ACPI setup yields more than 15 ports per (one of the) controllers? macOS will ignore the upper ones and you’ll be unable to complete the mapping.

In that case – and only in that case – you need to temporarily apply a kernel patch to disable that limit. That patching is notoriously buggy and unstable thus you need to enable it only for the purpose of mapping out your ports and then disable it. In OpenCore, patching is enabled by simply turning value of XhciPortLimit key to true (YES) in config.plist:

Building the map

Now, you need to draw yourself a map of the ports you are interested in and get ready to fill-in the details. Here’s how that looked like for me:

To build the map, you’ll use IORegistryExplorer. Start it up, make sure that nothing is added into the Search field and scroll down to where the XHC controllers are. Ideally, you would be using Bluetooth mouse and keyboard, which will leave all the USB ports empty and ready to identify, one by one.

If you do use USB mouse / keyboard then they will already appear, attached to their respective ports:

Mouse and keyboard are usually USB 2.0 devices, so you can immediately mark those logical ports as USB 2.0.

One of the ports will also be taken as Bluetooth USB 2.0 hub – all Bluetooth connected devices will appear here – for me that was XHC0/PRT2:

But, that aside, what is the best way to mark ports as either USB 3.0 or USB 2.0? You need device(s) that are 2.0/3.0 and plug them in. The best solution is to use external USB hub like the one I have here, from Anker:

What’s so great about it? It registers itself as both USB 2.0 and USB 3.0 device when plugged-in. In IORegExplorer, this looks like this:

Plugged-in device appears as green and clearly shows as 2.0 or 3.0 hub under its respective logical ports. When you pull the device out, these green lines become red and strike-through. With this, you know exactly how given physical USB port maps into logical ports.

Now you simply go through all the ports you have and entire map is done in like 10 minutes. For USB-C ports, I used Apple’s USB-A to USB-C adapter and plugged Anker’s hub that way.

That’s it, really. You have done your mapping. Don’t forget that motherboards have special USB connectors for USB-ports on the chassis. Depending on what kind of PC case you have, maybe you don’t have them connected. But if you do, procedure is the same with those ports too.

In the end, you will know which of the logical ports are used and which are not, for your specific hardware. All that’s left to do is create the .kext file.

Creating the USB-map.kext

Vanilla guide explains the important details of the structure you need to create, look for “So what kind of data do we shove into this plist?” on that page.

But that sample did not work for me, because it seems based on Mojave structure of the .kext, where Apple used IOKitPersonalities as the key while in Catalina it’s IOKitPersonalities_x86_64. So here’s my sample .kext, which you can use to build upon.

The top of the plist can be used to specify which manufacturer (maker) and which model is that kext for.

Then inside the mentioned IOKitPersonalities_x86_64 dictionary, you need to create another dictionary named as in this example:

where the most important part is to specify correct IONameMatch value. The rest of the values should hopefully remain the same, I simply copied them from Apple’s kext.

Inside the port structure, UsbConnector is a number that specifies type of the port, already explained in the guide:

0: USB 2.0 Type-A connector
3: USB 3.0 Type-A connector
8: Type C connector - USB 2.0-only
9: Type C connector - USB 2.0 and USB 3.0 with Switch, flipping the device **doesn't** change the ACPI port
10: Type C connector - USB 2.0 and USB 3.0 without Switch, flipping the device **does** change the ACPI port
255: Proprietary connector - For Internal USB ports like Bluetooth

Note that these values should already be specified for you, by the DSDT/SSDT. Type of connector is this part:

but I’m not sure this is always true though. I’ll need to see a lot of devices and configs to draw some firm conclusions. Here’s how the back I/O panel looks like for my motherboard:

All ports there are USB-A 3.x (thus using UsbConnector value of 3), except the TB3 port which is Type-C thus making it 9 as I did not notice any changes in the port map when flipping the cable.

When I briefly tested the motherboard in a case which has front USB-C port (connected to the 19pin connector on the mb), that port mapped into XHC0/PRT1 (USB 2.0 logical port) and PRT7 (USB 3.0 logical port).

When I tried a different cable, one that goes from same 19pin connector on mb but splits into two USB-A 3.0 physical ports, then one of those two mapped into that same PRT1+PRT7 pair while the other one mapped into PRT3+PRT8.

Which confirms my earlier note that full port mapping depends on the number of ports connected to every possible connector on the motherboard. So if it seems to you that some ports are unused, make sure to re-test that if you change cases where the PC build is housed-in.

port must be specified as Data; here I type just 03 and let PlistEdit Pro convert that for me. Don’t forget: port numbers are hexadecimal when entered into the value field thus port 10 is 0A, 11 is 0B etc.

Now, when you complete the map for the controller, take the highest port value and copy it one level up, as value for port-count key. The name of this key is confusing since it does not mean “total number of ports” but “highest port number used” instead.

Here’s what I ended up with:

Download that full USB-map.kext I created for my motherboard. It maps all back I/O ports + one USB-C front chassis port connected to motherboard 19-pin connector. Use it as example.

Place your USB map kext into EFI/OC/Kexts and add an entry for it in config.plist. With all that loaded, I got this display in IOReg:

You can see I did not re-map XHCITR as I don’t know how. I’m not sure how to reference it in SSDT nor in the .kext but fortunately I don’t have to since it just works. Its PRT3 is the USB 3.0 logical port for the back USB-C / TB3.

That’s all. Happy port hunting!

It’s really interesting that with custom SSDT you can rename devices as you want and thus change hardware configuration etc. Crazy stuff. Here’s some starting links if you want to learn more: Getting started with ACPI, A layman’s guide to creating a custom SSDT ↩︎
I think that Mykola wrote SSDT-XHC2.aml sample specifically for this ASRock board, since someone else who has the same motherboard asked him what to do on the Discord channel. ↩︎

Why you need to care about USB mapping

Sun, 09 Feb 2020 04:32:00 +0000

This was the most infuriating part of Hackintoshing for me. There are so many outdated, confusing, incomplete and downright wrong articles and forums posts, it beggars belief. Even for Intel-based Hacks, let alone AMD ones. Main issue is mix-up of historical context one needs to be aware of, with bewildering amount of inside-the-racket jargon that’s hard to grasp.

After spending multiple days on this alone I can say that none of the available guides is entirely correct nor clear what you should do and more importantly why you should do what they tell you to do.

When you choose some Mac model to emulate – say iMacPro1,1 – macOS will load USB hardware map for that particular machine. Apple knows exactly what their models use as hardware configuration so they don’t really need to scan for available ports or other hardware (like Windows or Linux must do). Everything is known before-hand. One thing they know is that none of their machines have more than dozen ports per USB controller thus in 10.11 (El Capitan) they introduced hard limit of 15 ports per controller.

On the other hand, general PC hardware is infinitely varying. Most motherboards feature large number of internal and external ports. It’s not uncommon to see 6-8 or even more USB ports on the back panel I/O. Additional ports which are present on chassis are connected to internal points on the motherboard. Each USB 3.0 port is also backwards compatible with USB 2.0 hence each physical port is counted as 2 logical ports. Then you have USB-C ports which are USB 3.0/2.0 compatible but are reversible so they need to be treated a bit special.

In general, depending on the chipset and motherboard features, that 15-port limit can be easily blown.

Saving point here is that there are usually multiple USB controllers in PC hardware; how many, it depends on the chipset and manufacturer choices. External USB hubs and other devices do not count here, since whatever you attach shares that one port where it’s attached.

What all this means in practice?

Most obvious consequence is that some of those ports you have will simply not work. macOS will ignore any port enumerated over 15th on particular controller. There is no specific logic which ones will that be but usually it first enumerates USB 2.0 and then 3.0 logical ports. It’s possible that some ports will be ignored even if they are below 15th, simply due to enforced port map of the emulated Mac; on my ASRock motherboard, ports 1 and 9 were removed on one of the 3 controllers.

As you’ll see, this map is not sequential and physical ports map to (more or less) random positions in the logical map.

Tools

You will need these two tools and you’ll run them on your Hackintosh.

MaciASL – automatically reads DSDT/SSDTs for the machine, can create new SSDT files in ASL format.
IORegistryExplorer to browse active ACPI setup. You can find this tool all over the Internet but if you have an Apple developer account, you can find it as part of Xcode 11 additional tools.

Know your hardware

When MaciASL opens, it automatically loads DSDT for the current system. You can filter that list of devices in the bottom part of the left panel and here I’m filtering per “XHC”.¹

So AMD’s X570 chipset on ASRock ITX/TB3 motherboard has 3 USB controllers. You can see two of them have 10 ports and one has 8 ports. Thus in theory, I should have no problem and all my ports should be working out of the box.

That’s only part of the story. DSDT can be augmented by manufacturer through a series of SSDTs. I assume this is done in layers because it allows them to have a base setup for particular chipset series and then customised for each particular model.

MaciASL can show you what SSDTs are active for the hardware. Here’s a screenshot when MaciASL is ran on MacBookPro13,3:

These additional tables can add, alter and/or hide devices you see in the DSDT.

Third layer of customisation is through OS device drivers. On macOS, this is done through .kexts. This third layer is primary source of confusion related to USB mapping for Hackintoshes. (More on that below.)

Thus to summarize:

DSDT / SSDT = coming through ACPI (firmware, I guess)
OS drivers (kexts) = specified in macOS

Now, when you run macOS on Apple’s hardware, Apple is the author of both the ACPI tables and kexts. When you run on non-Apple hardware, then original manufacturer (in my case ASRock) has done the ACPI part while Apple of course does macOS part.

Your final XHCI configuration — known as USB map in Hackintosh circles — is combination of these 3 layers: DSDT / SSDT / kexts. To see that final result, use IORegistryExplorer which will display all devices it finds on your system. When filtered per “XHC”, this is what it showed for my build:

Look closely and you’ll see a couple of strange things.

Ports listed under XHC1 controller are not named PRTx (as the DSDT declared) but are actually HSxx
Ports 1 and 9 are missing under XHC1
There’re two controllers named XHC0
There’s an additional XHCITR controller

Last discuss from bottom to the top.

This motherboard has Thunderbolt 3 port at the back I/O, managed by special TB3 controller. TB3 is also acting as regular USB-C port thus it has its own paired XHCI controller for that. So my motherboard has 3 XHCI controllers from the X570 chipset + 1 additional coming from (Titan Ridge) Thunderbolt 3.

The chipset has two XHC0 controllers but they are wired through different paths. It’s unfortunate for us that they are called the same (you’ll see why in the next article) but they are not problematic in general since they appear exactly as DSDT specifies.

XHC1 is the problem. Not only are ports renamed, two of them are missing. You probably already suspect why — macOS specifies an additional .kext that alters the port mapping setup in the hardware.

Know what you emulate

In my OC build, I chose to emulate iMacPro1,1 model. Thus the .kext macOS applies must be somehow connected to that particular machine.

Where are those .kext maps located? In /System/Library/Extensions and then:

in Mojave:
IOUSBHostFamily.kext/Contents/PlugIns/ AppleUSBXHCIPCI.kext/Contents/Info.plist
in Catalina:
IOUSBHostFamily.kext/Contents/PlugIns/
AppleUSBHostPlatformProperties.kext/Contents/Info.plist

I mentioned Mojave to point out just how much stuff can change. They did not change just the file location but also the internal structure. This is one more reason why you should never rush to update to major macOS releases. With the push towards DriverKit, kext are going away and who knows what’s going to change in 10.16.

When you open this Catalina .plist, this is the setup you’ll see:

Well, well, well…You can see that this map for XHC1 on iMacPro1,1 essentially overwrites ACPI setup for XHC1. Like it was never there…or?

Look closer though: this map also specifies SS02-SS06 ports which do not appear in the IORegistryExplorer. So what happens with those ports..?

To understand that, we need to look at the ACPI tables from the actual iMacPro, not from my build. If you know owner of one, you can ask them to run MaciASL for you 😉. Or you can look at this library of complete system dumps of various Mac models and find the one that interests you. For iMacPro, you’ll find the DSDT and 11 SSDTs:

DSDT has no XHCI setup, at all. XHC1 is declared in SSDT-10:

(SSDT-9 is also interesting, since it declares Thunderbolt 3 hardware.)

And there you go. SSDT declares all the possible ports and then .kext augments that list by hiding (and possibly renaming) some ports. But the .kext can’t manufacture ports in software - they must exist in hardware.

This is why in my build, which has 10 hardware ports under XHC1, I don’t see anything below HS10. But why is HS10 the last one visible, why not HS13? If you count the ports, my XHC1 has 10, while iMacPro’s is missing HS01 and HS09 so surely the next two in list should appear, right?

Well, no. These are just display names which are mostly irrelevant. What matters is the physical port address. Here’s HS10 port number in iMacPro:

and here it is on my build:

That’s how the ports match-up. Not through display name but through port address. HS12’s port number is 0x0C (12) which does not exist on my machine so the port is not showing up in IORegExplorer.

There are more details² here but I don’t understand them completely (yet). It’s out of scope for this article anyway.

I hope it’s now somewhat clearer just how complicated USB mapping is and why some ports on your PC appear dead. You can try switching SMBIOS to different Mac model and hope that things will be better. Community experience is that you are simply trading one set of problems for another.

On my machine, it turns out that XHC1/PRT1 is the logical 2.0 position for the top-left USB port on the back I/O. The other hidden port, XHC1/PRT9, maps into logical USB 3 for the bottom-right port on the back I/O. So depending on what kind of USB device I plug in, it may or may not work.

I’ll explain how to map-out your ports in the next article.

XHCI stands for eXtensible Host Controller Interface which deals with USB. Read on the Wikipedia if you are interested in the details. ↩︎
Like how exactly Apple uses the concept of USBCompanion ports to shuttle 2.0 logical port for each TB3/USB-c physical port to appear under XHC1 but keeps the 3.0 logical port under XHCTR. Lots of voodoo there. ↩︎