The current XHC USB Kext creation Guideline detailed below bases on the clever and sophisticated “kext as kext can or USB 3.0 without USBInjectAll.kext” approach originally developed by Brumbaer (see his extended guideline for all tiny details) for the ASUS Strix Z270i Gaming and allows the correct implementation of all else not natively implemented XHC USB 2.0 and USB 3.0 ports.
Thus, for the board-specific XHC USB kext creation, one can follow my guidelines detailed below for the ASUS Prime X299 Deluxe, or of course also follow Brumbear’s originating extended guideline for the Strix Z270i Gaming, which however unfortunately is German only….
Don’t be afraid! It is not that difficult as it looks like at the beginning! I really do explain stepwise and in all detail by means of the already successfully implemented XHC USB Kext Creation Approach for the ASUS Prime X299 Deluxe and SMBIOS iMacPro1,1 and how one is able to derive with minimum effort a board-specific XHC USB kext for any mainboard, e.g. also X99 or series 100, 200, 300 mainboards.
The resulting XHC USB Kext for the ASUS Prime X299 Deluxe and SMBIOS iMacPro1,1 is attached at the end of this originating post/guide: KGP-iMacPro-ASUS-PX299D-XHCI.kext
b.) Xcode distribution installed via the Appstore
c.) Command Line Tools installation via terminal command “xcode-select –install”
d.) KGP-iMacPro-Dummy-XHCI.kext attached at the end of this post (guide)
2.) Download and unzip KGP-iMacPro-Dummy-XHCI.kext. Rename the file to “User-SMBIOS-Brand-Board-XHCI.kext”. “User” , “SMBIOS”, “Brand” and “Board” are place holders for your Initials, SMBIOS, mobo-brand and mobo-denomination, e.g. KGP-iMacPro-ASUS-PX299D-XHCI.kext for my ASUS Prime X299 Deluxe and SMBIOS iMacPro1,1.
Note that the “Bundle identifier” nomenclature cannot contain blanks! Usually it shout start with the initials of your country, followed by your personal initials, USB and mainboard nomenclature, everything simply separated by dots.
d.) Now click on the triangle next to IOKit-Personalities and you will see that the Triangle symbol changes and the Xcode editor shows further content. Subsequently click on the triangles of “iMacPro1,1-XHC”, “IOProviderMergeProperties” and “ports” and you will see the following structure:KGP-iMacPro-Dummy-XHCI.kext
e.) Now click on each triangle next to HS01 to HS14 and SSP1 to SSP6 and you will see the following structure:
f.) Subsequently with a right click on one of the “port” and “data” entries, select “Show Raw Keys/Values”. Now we have everything ready to start with the actual work:
Note that there are 14 HSxx and 6 SSPx port entries in the XHC USB Dummy Kext, where “HS” stands for “High Speed” Port, “SSP” for “Super Speed Port” and “xx” or “x” for the port number. HS ports start with hexadecimal port counter “<01000000>”, which corresponds to decimal “1”. The last hexadecimal HS port counter is “<0e000000>”, which corresponds to decimal “14”. The SSP boards start with the hexadecimal port counter “<10000000>”, which corresponds to decimal “16”. The last hexadecimal port counter is “<15000000>”, which corresponds to decimal “21”. Thus we can see, that the HS counter goes from 1-14 (14 ports) and the SSP port counters from 16-21 (6 ports). One might ask what about port counter 15 and 16? These two port counters are reserved for two dummy ports, apparent in the IOReg under IOACPIPlane implemented as USR1 and USR2. These dummy ports however, are of no interest for us.
The “USB Connector Number” defines the connector type:
“0” stands for standard USB2.0 Type-A and is always a HS port property only
“3” stands for standard USB Gen 1 Type-A (USB 3.0) and is therefore always both a HS and SSP port property.
“9” or “10” denotes USB Gen 1 Type-C (USB 3.0) and is a HSS and SSP port property. SSP-ports attributed to USB Gen 1 Type-C (USB 3.0) connectors can be “9” or “10”, whether the respective device/cable can be connected in both (9) or just in one direction (10). The respective HS port receives the same assignment.
“255” can be a HS and SSP port property. Usually 255 is attributed to internal USB2.0 headers connected to internal devices (like e.g. AURA in case of the ASUS Prime Deluxe on HS14). However, in this case, 255 is a HS property only. Although most internal devices tend to be USB2.0, there are existing examples of USB internal devices. A common case for desktops is an internal USB hub (may be part of the case or an internal hub on the board itself). Usually it can even happen like in case of the the three external mobo back panel USB3.0 Type-A connectors of the ASUS Prime X299 Deluxe (all three connectors are assigned to HS06 and SSP6), that even some of the external back panel USB3.0 mainboard connectors share such internal USB3.0 hub/bridge. Thus in case of the ASUS Prime X299 Deluxe one needs to attribute “255” instead of “3” to HS06 and SSP6, assigned to all three respective external USB3.0 connectors. In the future, we may even see seeing USB3 BT controllers, trackpads, Webcams, etc., although rather on Laptops than desktops , respectively.
i.) External USB3.0 connectors always share one HS and SS port to work with both USB2.0 devices (HS) and USB3.0 devices (SS). Internal USB3.0 headers are usually even assigned to two HS and SS ports.
ii.) External USB2.0 connectors are assigned to one HS port only. Internal USB2.0 headers are usually assigned to two HS ports. External USB2.0 connectors or internal US2.0 headers are never assigned to any SS port, which is US3.0 property only.
iii.) All HS and SS ports assigned to external USB3.0 connectors or to internal USB3.0 headers connected to external USB2.0 or USB3.0 devices must have USB Connector Number “3” (external) in the kext
iv.) All HS ports assigned to external USB2.0 connectors or internal to USB2.0 headers connected to external USB2.0 or USB2.0 devices must have USB Connector Number 0 (USB2.0 external) in the kext.
v.) All HS ports and SS ports (USB3.0 only) of internal headers connected to internal devices (e.g. AURA on ASUS mobos) should be attributed to USB Connector Number 255 (internal) in the kext. This also states for all external USB3.0 motherboard back panel connectors likely sharing an internal onboard USB3.0 hub/bridge. Devices plugged to such external onboard USB3.0 connectors would all popup in IOREG under the same HS and SSP port).
vi.) USB3.1 connectors are usually assigned to different controllers than XHCI and should never be part of any XHC USB kext.
3.) Preconditions for point 4.) below:
I.) You must have also all internal USB 2.0 and USB 3.0 connectors connected with respective USB front panel plugs! This is really a very important precondition! You should have in mind that you want to establish a COMPLETE XHC USB KEXT for your specific mainboard. Thus it is therefore not sufficient just to implement the external USB 2.0 and USB 3.0 on-board connectors! Your fully implemented XHC USB KEXT must really consider all connectors available on your particular mainboard, especially as you will subsequently distribute your board-specific XHC USB Kext to the community. It therefore has to be applicable for the most general case, which indeed ist the usage of all internal and external USB 2.0 and USB 3.0 ports available on your particular mainboard!
II.) Use the correct USB port limit KextToPatch entry for your actual MacOS version, if available.
III.) You should not have any USB related kext in your EFI-folder (also not the ones attached to this guide) for the original port discovery. This will force OS X on boot to load the emergency USB system driver configuration, which is of crucial and particular interest for the subsequent XHC USB creation.
IV.) Start the IORegistryExplorer.app. The IOService (plane) provides a listing of all installed services.
Scroll down until you see your specific XHC controller entry.
For the ASUS Prime X299 Deluxe it is XHCI. There are two entries. The PCIDevice Driver “XHCI@14” and the XHCI driver “XHCI@14000000”.
a.) By clicking on XHCI@14 you find the “class-code” entry (in case of the ASUS Prime X299 Deluxe “30 03 0c 00”), the “device-id” entry (in case of the ASUS Prime X299 Deluxe “af a2 00 00”) and the “vendor-id” (in case of the ASUS Prime X299 Deluxe “86 80 00 00”). This are raw data from the control registers, thus the values are slightly flipped around. In reality “0X8068” stands for Intel and “0xa2af” is the device-ID of the ASUS Prime X299 Deluxe on-board XHC Controller CHIP. Thus the “IOPCIPrimaryMatch”-ID of the ASUS Prime X299 Deluxe Mainbaord on-board XHC Controller is “0xa2af8086”.
Important note: In case your on-board XHC Controller’s “IOPCIPrimaryMatch”-ID is different from “0xa2af8086”, all steps subsequent to 5b.) below will fail.
The Info.plist of KGP-iMacPro-ASUS-PX299D-XHCI.kext and KGP-iMacPro-Dummy-XHCI.kext (attached at the end of this originating post/guide) contains an additional kext with AppleUSBXHCIPCI-Driver entries specific for the ASUS Prime X299 Deluxe on-board XHC Controller with the “IOPCIPrimaryMatch”-ID “0xa2af8086”, namely “AppleUSBXHCISPT“. This AppleUSBXHCIPCI-Driver driver is loaded and implemented during each boot process and communicates with the ASUS Prime X299 Deluxe specific on-board XHC-Contoller. The name of the additional kext in the Info-plist of KGP-ASUSPrimeX299Deluxe-USB.kext and KGP-Dummy-USB.kext is “AppleUSBXHCISPTB iMacPro1,1”, in correspondence to the chosen AppleUSBXHCIPCI-Driver and SMBIOS Configuration.
Thus, in case that the “IOPCIPrimaryMatch”-ID of your board-specific on-board XHC-Controller is different from “0xa2af8086”, you have to find the correct AppleUSBXHCIPCI-Driver different from AppleUSBXHCISPT within the driver entries of “AppleUSBXHCIPCI” ! To do so perform the following steps:
i.) In the Finder Window go to the /S/L/E directory of your system disk and copy the IOUSBHostFamily.kext to your desktop.
ii.) Right-click on the IOUSBHostFamily.kext and select “Show Package Contents”. Double click on “Contents” and “Plugins” and you will see the following list of kexts:
Right-click on AppleUSBXHCIPCI.kext and once more select “Show Package Contents”. Double-click on “Contents” and subsequently double-click on “Info.plist” to open the Info.plist of the AppleUSBXHCIPCI.kext with Xcode. You will find the following content:
Click on the triangle in front of “IOKitPersonalities” to unfold its content.
You will find a list of AppleUSBXHCIPCI-Driver entries marked by the red rectangle.
Now click on the triangle of each driver entry to show the content. The first entry important for us is the “IOPCIPrimaryMatch”-ID of each specific driver. The appropriate driver for your board-specific on-board XHC controller should be the one with the “IOPCIPrimaryMatch”-ID closest to the “IOPCIPrimaryMatch”-ID off your XHC on-baord controller. Remember that you already derived above the “IOPCIPrimaryMatch”-ID of your XHC on-baord controller by means of the IORegExplorer “Vendor-ID” and “Device-ID” entries under “XHC@14”! In case of the ASUS Prime X299 Deluxe the correct choice was the AppleUSBXHCIPCI-Driver “AppleUSBXHCISPTB” with the “IOPCIPrimaryMatch”-ID “0xa12f8086”, likely already used for the previous version of the ASUS PRIME X299 Deluxe on-baord HXC USB Chipset and controller.
Let me describe by means of another example for the ASUS X99-A II, how to properly adopt and modify the the additional kext entries implemented in the Info.plist of KGP-iMacPro-Dummy-XHCI.kext.zip for your board-specific XHC Usb Controller Chipset.
The “IOPCIPrimaryMatch”-ID of the ASUS X99-A II on-board XHC controller is “0x8d318086”, the respective driver with the closest “IOPCIPrimaryMatch”-ID appears to be AppleUSBXHCIPLTH with a IOPCIPrimaryMatch-ID of “0x8c318086”.
Always keep in mind that the entire approach is a kind of blind guess approach, as you might not be able to find the exact IOPCIPrimaryMatch-ID match between the respective AppleUSBXHCIPCI-Driver and your XHC on-board controller. For the ASUS X99-A II on-board XHC controller with IOPCIPrimaryMatch-ID “0x8d318086” we choose AppleUSBXHCIPLTH with a IOPCIPrimaryMatch-ID of “0x8c318086”, which again might be the AppleUSBXHCIPCI-Driver for the previous version of the ASUS X99-A II on-board XHC controller chipset.
iii.) Now in case of the ASUS X99-A II, one would open the Info.plist contained in KGP-iMacPro-Dummy-XHCI.kext with Xcode and change the following ASUS Prime X299 Deluxe specific additional kext entries, in concordance with the match results for the ASUS X99-A II mobo’s onboard XHC-controller:
Thus the final correct additional kext entries for the ASUS X99-A II finally would look like this:
Don’t forget to save the modified Info.plist of KGP-Dummy-USB.kext with the new now hopefully correct additional kext entries for the AppleUSBXHCIPCI-Driver and your specific XHC on-board controller!
iv.) If your somewhat blind guess driver-match choice was correct or not will be revealed at point 5 c.) below, where your USB 3.0 ports already should be fully functional, of course by always supposing that you also successfully and entirely implemented and completed points 5 a.) and 5 b.) before! If 5 c.) fails, you have to continue with the search for the appropriate driver with the closest IOPCIPrimaryMatch-ID to your XHC onboard controller, possibly to modify the additional kext entries described above and to repeat 5c.) until your USB 3.0 ports are fully functional. The repetition of 5a.) and 5 b.) would not be necessary if successfully and entirely implemented and completed once!
Finally it should be noted that for the ASUS Prime X299 Deluxe USB kext development there was no need to change the AppleUSBXHCIPCI-Driver originally meant for the Strix Z270i Gaming! The IOPCIPrimaryMatch-ID of the XHC Controller used on both boards was absolutely identical! Thus, there might also be no need for changing the AppleUSBXHCIPCI-Driver for other ASUS X299 mainboard models, or X299 mainboard models of different brands. Unfortunately, I already returned the Gigabyte AORUS X299 Gaming 9, thus I could not check the latter board for AppleUSBXHCIPCI-Driver compatibility.
b.) By clicking on XHCI@14000000, one finds in the “IOClass” and “CFBundleIdentifier” entries the active USB
driver, which is “AppleUSBXHCIPCI“. Under “name” entry one finds the name of the XHC controller, which is “XHCI” in case of the ASUS Prime X299 Deluxe.
As you can see else, one finds in the IOReg the same HS and SS port entries already discussed with respect to the kext structure above. The controller numerates the individual ports. Port 0 (XHCI@14000000) is the Hub. Ports with plugged devices are indicated by triangles and can be unfolded by clicking on the triangles to see the content information for the connected device. The SS-Ports are non-functional yet.
5.) Well lets start now with the mainboard specific XHC USB port assignment and configuration.
a.) The port-count value is defined by the HEX port number of the highest SSP-port in use in your particular USB XHC kext configuration
To find the correct value for your mainboard investigate the OSX USB Emergency configuration (no USB kext in your EFi-Folder)
On the ASUS Prime X299 Deluxe the highest SSP port is SSP6, with hex port number 16000000. Thus, your SSPx port numbers range from 11000000 (SSP1) to 16000000 (SSP2) as also implemtned in the standard kext.
Without a port limit patch you can also investigate investigate the lowest hex port number of SSP1 (110000) in Apple’s USB Emergency configuration.
and logically implemented the hex port numbers of the higher SSP ports.
The SSP hex port numbers must not always range from 11000000 to 16000000, though. E.g. in case of the ASUS X99-A II, lowest SSP hex port number is 10000000 and highest hex port number is 15000000, which further also implies a port-count hex number of 15000000.
In such case, you have to adopt your kext following your IOREG investigation under the OSX USB emergency configuration.
b.) Now we will start with the HS port discovery: Take a USB 2.0 Device under the OSX USB emergency configuration (no Usbkext in your EFI-Folder) and connect it with the first USB Front Panel Connector. In my case, it is an external USB 3.0 Connector connected to an internal USB3.0 header. As you will see, the device immediately shows up in the IORegistry Explorer under the respective HS port.
If you remove the USB 2.0 Stick, the related information will turn red…
Very important information! Now you know that the first external USB 3.0 front panel connector connected with one of the two internal USB3.0 onboard headers is linked with port HS03. Write down external USB3.0 connector position, USBConnector type, internal USB3.0 onboard header denomination, as well as the HS03 port number and assign USBConnector number (3) to HS03 in your kext.
Now repeat the procedure for all front-panel and mainboard back-panel USB 2.0 and USB 3.0 connectors, and carefully write down USB connector position, USB connector type, connector or internal USB3.0 onboard header denomination as well as HS port number and assign the adequate USBConnector number to the respective HS port properties within your kext.
c.) Now save your kext and implement it in the EFI-directory of your system disk and reboot reboot your system.
d.) As all SSP ports within the kext already have attributed USBConnector number 3 by default, your USB 3.0 connectors now will be already fully functional!
If this is not the case, remember that you might have chosen the wrong AppleUSBXHCIPCI-Driver for your particular on-baord XHC USB controller chipset, and you might have to repeat steps 4 ii.) and iii.). Double check also before if you properly and entirely performed and implemented points 5a.) and 5b.) above.
For the SSP port discovery, connect this time a USB3.0 device one after the other to all respective USB3.0 connectors, by investigating at wich SSP ports the USB 3.0 device pops up in IOREG when connected to each specific USB 3.0 connector. Like before, write down external USB3.0 connector position, USBConnector type, internal USB3.0 onboard header denomination, as well as the SSPx port number.
Now you should know your complete HS and SS port assignment.
e.) Finally investigate your notes which HS and SS ports have not been used during your port discovery. Cross-check if such ports might be part of some internal USB headers connected to internal devices. If, so also write the down all respective information and attribute the correct USB Connector number (255) to respective HS or HS and SS ports. It is very unlikely that not all 20 HS/SSP ports are used by your mobo. However, if after the entire port discovery there are indeed unused HS and SPP ports in your kext, simply drop them from the kext. If you would remove SSP6, don’t forget to also to update your port-counter value in the kext.
Now you can implement your port discovery notes within some port-layout.rtf, which you should add to your kext besides the info.plist. My port discovery notes for the ASUS Prime Deluxe are once more summarised below.
+++++++ Frontpanel: 2x USB 3.0 external connected with internal USB3.0 header U31G1_12 2x USB 3.1 Gen1 U31G1-1 U31G1-2 HS01 (3) HS02 (3) SSP1 (3) SSP2 (3) +++++++ Frontpanel: 2x USB 3.0 external connected with internal USB3.0 header U31G1_34 2x USB 3.1 Gen1 U31G1-3 U31G1-4 HS03 (3) HS04 (3) SSP3 (3) SSP4 (3) +++++++ Frontpanel: 2x USB 2.0 external connected with internal USB2.0 header USB78 2x USB2.0 USB7 USB8 HS08 (0) HS07 (0) +++++++ Back-Panel, 1st row at the top: 2x USB3.0 external connected to a internal USB3.0 onboard hub/bridge; LAN2_U31G1_E34 USB 3.1 Gen 1 U31G1_E3 U31G1_E4 HS06 (255) HS06 (255) SSP6 (255) SSP6 (255) +++++++ Back-Panel, 2nd row from top: 1x USB 3.0 external, 1x USB3.0 external connected to some internal USB3.0 onboard hub/bridge; LAN1_U31G1-E2_5 USB 3.1 Gen 1 U31G1-E5 U31G1-E2 HS05 (3) HS06 (255) SSP5 (3) SSP6 (255) +++++++ Back-Panel, 3rd row from top: 4x USB 2.0 external; USB9~12 USB12 USB11 USB10 USB9 HS12 (0) HS11 (0) HS10 (0) HS09 (0) +++++++ 2x USB 2.0 internal connected to internal USB2.0 devices (HS ports not associated to any physical USB onboard connector/header) port 13 port14 HS13 (255) HS14 (255) +++++++
g.) If the kext is successfully loads during boot, the XHCI@14000000 entry in the IOREG will provide something like the following information:
Now benchmark the different USB 2.0 and USB 3.0 ports by means of e.g. Black Magic Speed Test. Note that the benchmark scores always will depend on the USB device used for the Benchmark!
Enjoy and have fun,