[USBMapping] Link to incomplete docu

[rowild]

Please stop and read this carefully. Otherwise your issue will be left unanswered and closed.

We require the following for guide issues:

• Guide(s) in question
  USB MAPPING

• Link to page(s) with the issue
  https://dortania.github.io/OpenCore-Post-Install/usb/intel-mapping/intel.html

• Clearly explain the issue(s) with the page(s) (if there is a visual issue, a screenshot is required)
  The page recommends to read a docu to which it links:
  https://github.com/corpnewt/USBMap
  but that docu does not include a real how-to, but "only" a history lesson (which is cool and informative). A newbie like me is now totally lost and discouraged - having come so far, and suddenly: nothing. IMO this is a no-go and really needs to be fixed ASAP.

• Include possible fixes
  I cannot offer a fix, since I am not familiar with that subject. (I am learning it.)

In the "Issue" guideline you mention:
"Note we only maintain Dortania guides, so please do not open issues for other guides."
Hmmm... guess this is one that does not really go along with that statement... :-)

Any chance to provide the promised re-write?

[rowild]

Don't know, why it is labelled as error... I didn't add a label, and clicking on it didn't give me any options... sorry!

[khronokernel]

Oh hello!

Don't know, why it is labelled as error... I didn't add a label, and clicking on it didn't give me any options... sorry!

No worries, when you open an issue it auto-adds the flair. We usually clean them up when we get a good look at the issues

Any chance to provide the promised re-write?

We do plan to have a proper USB Map rewrite at some point, however it's mostly an issue about time for our team members. I'm the main author for the majority of Dortania, however most of this was done during my medical leave where I had quite a bit of extra time on my hands. Now that all of our members are either back to work or school, it's become much more difficult to put time into large scale rewrites. I have a couple PRs over 6 months+ old that are still set as drafts.

Regarding loose timelines, I'm hoping to have some more free time in May to:

• Write a proper outline
• Grab test cases for multiple hardware gens(ie. OHCI/EHCI, Ivy Bridge-Broadwell, Skylake+ and AMD edge cases)
• Grab images and example files
• Flesh out proper guide

It's also an issue of priority however, as I do need to maintain the main install guide, as well as a growing priority with Opencore-Legacy-Patcher. However with the close call that was XhciPortLimit in 11.3 beta 2, it is a higher priority than most issues in the guides

[dreamwhite]

Don't know, why it is labelled as error... I didn't add a label, and clicking on it didn't give me any options... sorry!

Don't worry it's normal ^^

Regarding your issue, probably you can give a look at PR 54, despite it wasn't well seen from dortania's team.
I don't wanna create a big flame but honestly... There's no UNIVERSAL method which can help you mapping your USB and I wanna highlight that if you're going to map your USB, at least you're a little bit more skilled than the average user which just follows the OpenCore-Install-Guide without taking care of Post-Install guide.
There are different methods that can lead to the same result like the kext method (which personally I only consider when we're talking about ASUS/MSI Z490 boards, or on AMD/Intel HEDT platforms), or the SSDT method (which I suggest if your motherboard firmware has a dedicated SSDT for the USB mapping like xh_rvp08).

[khronokernel]

There's no UNIVERSAL method which can help you mapping your USB

We've gone over this dreamwhite, disabling the root hub and rebuilding the map is a valid form of USB mapping. This is what USBmap.py relies on as well, and what we recommend in the manual mapping guide when ports are not visible or requires a rename due to multiple controllers of the same name.

Your guide had too many holes in it, which we mentioned how to resolve however you shot down the idea and asked us to pick the PR up.

Regardless, this specific issue is about the semi-automated usage of USBmap.py, not manual mapping so please avoid derailing the issue.

[dreamwhite]

There's no UNIVERSAL method which can help you mapping your USB

We've gone over this dreamwhite, disabling the root hub and rebuilding the map is a valid form of USB mapping. This is what USBmap.py relies on as well, and what we recommend in the manual mapping guide when ports are not visible or requires a rename due to multiple controllers of the same name.

Your guide had too many holes in it, which we mentioned how to resolve however you shot down the idea and asked us to pick the PR up.

Regardless, this specific issue is about the semi-automated usage of USBmap.py, not manual mapping so please avoid derailing the issue.

My bad .-.

[rowild]

Thank you for your lightning fast responses! – Not being a native English speaker I am not sure what "medical leave" exactly means. I hope your are doing fine and all is well, @khronokernel !!!
IMO the problem here is that the docu itself links to a docu that does not explain it :-)

[khronokernel]

IMO the problem here is that the docu itself links to a docu that does not explain it :-)

Yes, main issue is we don't really have any guides that are better we want to link to. There's guides based on hackintool however the backend is built off USBmap.py v1 instead of the new USBmap.py v2 which includes more advanced mapping techniques.

We're more comfortable either linking to the source, or writing ourselves when possible

[dreamwhite]

Good evening @khronokernel,
I have a small doubt regarding USB mapping (both with USBMap and SSDT methods):
according to dortania's USB Mapping Guide USB 2 port type has 0 as value.

Let's suppose that we're on a Desktop (which has a Front-Panel and a Back-Panel) and we're mapping a USB3 port located in the Front-Panel.

My question is: if we're mapping this USB3 Type-A front-panel port, which value should we use for the USB2.0 port personality?

From what my """"experience"""" can tell, only the back-panel USB2 ports can have 0 as port-type value, while USB2 Type-A front-panel ports should have 255 (aka 0xFF) port-type value since the front-panel wire effectively is connected on an internal header of the motherboard.

Is this assumption wrong, or goes against ACPICA _UPC ports specification in any way?
If not, shouldn't the guide be updated with a small description of the USB type Proprietary connector by specifying that this kind of value must be used for USB2 personality ports of front-panel (and even laptop's microSD card reader and laptop's webcam)?

Thank you so much and have a great weekend

[khronokernel]

My question is: if we're mapping this USB3 Type-A front-panel port, which value should we use for the USB2.0 port personality?

Set it to what the physical port is, for example on 1 USB 3.0 port:

• HS01: Set to 0x3
• SS01: Set to 0x3

while USB2 Type-A front-panel ports should have 255 (aka 0xFF) port-type value since the front-panel wire effectively is connected on an internal header of the motherboard.

Internal header actually doesn't determine what personality it has, it's more what kind of port is it used for by the user. 0xFF have a higher wake priority over other USB devices as it's commonly routed for Bluetooth.

Note however, whenever you set a port to 0xFF you actually disable that port's hot swap capability in macOS. Note devices that are not directly attached are not affected, so USB hub devices or SD card readers can stay on 0xFF is desired.

If not, shouldn't the guide be updated with a small description of the USB type Proprietary connector by specifying that this kind of value must be used for USB2 personality ports of front-panel (and even laptop's microSD card reader and laptop's webcam)?

Seems reasonable to me, I can add that part sometime this weekend

[dreamwhite]

0xFF have a higher wake priority over other USB devices as it's commonly routed for Bluetooth.

Oh, I never heard about that. Sounds interesting. Can you gently link any resource if you have it?

Note however, whenever you set a port to 0xFF you actually disable that port's hot swap capability in macOS. Note devices that are not directly attached are not affected, so USB hub devices or SD card readers can stay on 0xFF is desired.

Uhm... I don't want to put in doubt your words but I always used 0xFF connector type for front-panel ports and never had issues before with hot-swapping. Am I lucky or what? 😅

Seems reasonable to me, I can add that part sometime this weekend

Thank you so much. A small note: I gave a quick look at my USB map and noticed that my microSD card reader port (HS06) has 0x00 as connector type. The only connectors that are defined as 0xFF are the bluetooth port (HS07) and the integrated webcam (HS05). Theorically, as you said it's fine, right?

[rowild]

Mac can do hot-swapping?? Are you talking, by any chance, of exchanging or turning on/off hard drives while the OS is running?

[khronokernel]

Mac can do hot-swapping?? Are you talking, by any chance, of exchanging or turning on/off hard drives while the OS is running?

@rowild Mainly discussing swapping USB devices

[rowild]

Ah, ok. But since it came up, even though off-topic: do you happen to know if macOS is capable of hot-plugging hard discs like windows can?

[khronokernel]

The OS itself supports SATA hot-plug, however actual functioning hot-plug is reliant on the SATA controller and firmware. It's mostly a try and see if it works for built-in SATA controllers on motherboards