search

corpnewt / USBMap

Python script for mapping USB ports in macOS and creating a custom injector kext.
MIT License
1.04k stars 88 forks source link

Guide snaglist #58

Open williamcorney opened 1 month ago

williamcorney commented 1 month ago

There were a few steps of guide I was unclear about.

  1. What if any circumstances should we use this option in USBmap menu? -

    "Generate ACPI To Reset RHUBs"?

    This produces a DSL file. Am I supposed to use maciASL to save it as a asm file ?

  2. Toggle or disable all? - step 7 Toggle off all port personalities that you didn't encounter when using "Discover ports" OR Disable any of the first 15 port personalities that are not used for a keyboard or mouse

  3. Port personalities were disabled in step 7 not step 6.

  4. Does this refer to external USB 2 hubs ( as opposed to USB2 ROOT hubs ?)

    Supports mapping USB 2 HUBs (requires the HUB's parent port to use type 255

  5. In the case of a physical port that supports USB 2 and USB3 . Should I set both personalities to 3 or 2 and 3 respectively?

    Does this look look correct from the screenshot??

         Screenshots show from 1-4 the stages from start to finished work

steps

corpnewt commented 1 month ago

What if any circumstances should we use this option in USBmap menu?

If the current USB controller names match built-in injectors, USBMap will state that they need to be renamed before mapping. Typically you'd use the XML plist renames instead of ACPI - but I included both for the sake of covering bases. It only generates a .dsl file as you are expected to verify the info. Since you're already booted into macOS, the ACPI has likely been altered by your boot manager, and is not guaranteed to be accurate.

Toggle or disable all? - step 7 Toggle off all port personalities that you didn't encounter when using "Discover ports" OR Disable any of the first 15 port personalities that are not used for a keyboard or mouse

This should be fairly clear per the subtext under step 7:

◦ Disable any of the first 15 port personalities that are not used for a keyboard or mouse - EVERYTHING ELSE in the first 15 can be disabled ◦ Disabling these is ONLY TEMPORARY and done for the sake of mapping - you can still choose which to include in the final map ◦ DO NOT disable port personalities 16 through 26, these need to stay enabled to continue mapping

The idea is you disable anything you've already seen (so only within the first 15 port personalities per IOKitPersonality), but that aren't essential to interacting with your system for the purpose of mapping (like a keyboard/mouse).

Port personalities were disabled in step 7 not step 6.

I've corrected the typo in the latest commit, thank you.

Does this refer to external USB 2 hubs ( as opposed to USB2 ROOT hubs ?)

No, only USB 2 hubs under EHCI controllers. EHCI controllers will often have one or more port personalities that act as a hub, which will have several port personalities that enumerate underneath them. macOS needs those mapped as well, and that's what that text is referring to - it is not referring to a USB hub under an XHCI controller, or an external USB 2 hub.

In the case of a physical port that supports USB 2 and USB3 . Should I set both personalities to 3 or 2 and 3 respectively?

As mentioned in the quick start already - the "type" refers to the physical port, not the port personality. If it is a physical USB 3 Type-A port, both personalities would use type 3. If it is a physical USB 2 Type-A port, there is only one personality, and that would use type 0.

I cannot vouch for the correctness of your map without physical access to your machine and having mapped it myself - so I cannot say, sorry.

-CorpNewt