SSDT USB Mapping #54
SSDT USB Mapping #54
Conversation
|
So this is my initial read through, will need to look at this closer this weekend about merging:
I'm unsure how familiar you are with VuePress, so to add new pages to the sidebar you'll want to edit the config.js Around line 127: title: 'USB Mapping',
collapsable: true,
sidebarDepth: 2,
children: [
['/usb/intel-mapping/intel', 'Intel USB mapping'],
- ['/usb/manual/manual', 'Manual Mapping'],
+ ['/usb/manual/manual', 'Manual Mapping'],
+ {
+ title: '',
+ collapsable: false,
+ sidebarDepth: 2,
+ children: [
+ ['/universal/manual/ssdt', 'SSDT Method'],
+ ['/universal/manual/kext', 'Kext Method'],
+ ]
+ },
]Note: For the config.js, don't add the .md suffix, VuePress will likely error out on build as it'll look for a Overall with this PR, quite liking the addition of SSDT mapping. It was an idea I had, however was something I wasn't able to justify putting time into. Like I mentioned earlier, I plan to look at all the PRs properly this weekend so I'll have more critiques then. |
|
Alright,I've pushed the changes, removed the direct reference to Maldon, let me know if any other changes is required for that matter Also, I'm not the best with vue, but I've tried to apply the changes you mentioned, please check if I messed with it or if it's fine I splitted the guide in two, the guide seemed too long indeed... And I renamed your title to "Kext creation method" in order to let the user know that it's either one or the other, and at the end of the SSDT guide you are not confused by the "Creating our kext" title as if there were other steps to follow, I'd like to know your opinion on that too Ale |
Thanks Gengik84 for the tip
|
@1alessandro1 Hi, when you disable usb port, you can use 0x00,0x03 etc.. but it's not very important if the first arg is Zero |
Thanks, I applied the changes you mentioned here in the guide, line 112
|
|
Also if the port is going to be useful further (users can choose to change which ports they may require if they're too many) I would suggest to specify the connector type properly even if the port is disabled, (with no functional differences, but more practical ones) so when one should come back and disable/enable other ports basing on their needs those connectors are already correctly defined Take for example a Gigabyte Z390 with lots and lots of 3.0 ports (hence 2.0 ports) which are way over the 15 port limit, and the user decides to disable some 3.0 port in order to connect USB mouse/keyboard on the back panel - they would disable the correspondant 3.0 port with |
|
|
||
|  | ||
|
|
||
| The unmodified, original ACPI table has a lenght of `2835`, this is going to be useful later in the guide, when we're going to tell OpenCore to avoid loading that table in favour of the new one we're going to modify. |
There was a problem hiding this comment.
Almost all of the time the ACPI for the root hub is located in the DSDT, so this is going to be useless. I suggest creating a new root hub and _STAing the old one instead.
There was a problem hiding this comment.
the ACPI for the root hub is located in the DSDT, so this is going to be useless.
The RHUB in the DSDT only defines the _ADR of the port not the connector type. This method is valid for skylake and newer (I have to add this warning in the guide) hence it is necessary to block the relative SSDT which uses GUPC or similar
There was a problem hiding this comment.
In many cases the ports are defined later in the DSDT; for example:
Skylake laptop
Scope (_SB.PCI0.XHC.RHUB.HS01)
{
Method (_UPC, 0, Serialized) // _UPC: USB Port Capabilities
{
Return (UUPC (0xFF, 0x03))
}
Method (_PLD, 0, Serialized) // _PLD: Physical Location of Device
{
Return (UPLD (One, One))
}
}
Scope (_SB.PCI0.XHC.RHUB.HS02)
{
Method (_UPC, 0, Serialized) // _UPC: USB Port Capabilities
{
Return (UUPC (0xFF, 0x03))
}
Method (_PLD, 0, Serialized) // _PLD: Physical Location of Device
{
Return (UPLD (One, 0x02))
}
}
...
AMD desktop, PTXH
Device (PTXH)
{
Name (_ADR, Zero) // _ADR: Address
Method (_PRW, 0, NotSerialized) // _PRW: Power Resources for Wake
{
Return (GPRW (0x19, 0x04))
}
Device (RHUB)
{
Method (GPLD, 2, Serialized)
{
Name (PCKG, Package (0x01)
{
Buffer (0x10){}
})
CreateField (DerefOf (PCKG [Zero]), Zero, 0x07, REV)
REV = One
CreateField (DerefOf (PCKG [Zero]), 0x40, One, VISI)
VISI = Arg0
CreateField (DerefOf (PCKG [Zero]), 0x57, 0x08, GPOS)
GPOS = Arg1
Return (PCKG) /* \_SB_.PCI0.GPP2.PTXH.RHUB.GPLD.PCKG */
}
Method (GUPC, 1, Serialized)
{
Name (PCKG, Package (0x04)
{
Zero,
0xFF,
Zero,
Zero
})
PCKG [Zero] = Arg0
Return (PCKG) /* \_SB_.PCI0.GPP2.PTXH.RHUB.GUPC.PCKG */
}
Name (_ADR, Zero) // _ADR: Address
Device (SS01)
{
Name (_ADR, One) // _ADR: Address
Method (_UPC, 0, NotSerialized) // _UPC: USB Port Capabilities
{
Return (GUPC (One))
}
Method (_PLD, 0, NotSerialized) // _PLD: Physical Location of Device
{
Return (GPLD (One, 0x06))
}
}
Device (SS02)
{
Name (_ADR, 0x02) // _ADR: Address
Name (_UPC, Package (0x04) // _UPC: USB Port Capabilities
{
0xFF,
0x09,
Zero,
Zero
})
Method (_PLD, 0, NotSerialized) // _PLD: Physical Location of Device
{
Return (GPLD (One, One))
}
}
...
AMD desktop, XHC0
Scope (_SB.PCI0.GP13.XHC0)
{
Device (RHUB)
{
Name (_ADR, Zero) // _ADR: Address
Device (PRT1)
{
Name (_ADR, One) // _ADR: Address
Name (_UPC, Package (0x04) // _UPC: USB Port Capabilities
{
0xFF,
0x03,
Zero,
Zero
})
Name (_PLD, Package (0x01) // _PLD: Physical Location of Device
{
ToPLD (
PLD_Revision = 0x2,
PLD_IgnoreColor = 0x1,
PLD_Red = 0x0,
PLD_Green = 0x0,
PLD_Blue = 0x0,
PLD_Width = 0x0,
PLD_Height = 0x0,
PLD_UserVisible = 0x1,
PLD_Dock = 0x0,
PLD_Lid = 0x0,
PLD_Panel = "BACK",
PLD_VerticalPosition = "CENTER",
PLD_HorizontalPosition = "LEFT",
PLD_Shape = "VERTICALRECTANGLE",
PLD_GroupOrientation = 0x0,
PLD_GroupToken = 0x0,
PLD_GroupPosition = 0x1,
PLD_Bay = 0x0,
PLD_Ejectable = 0x1,
PLD_EjectRequired = 0x0,
PLD_CabinetNumber = 0x0,
PLD_CardCageNumber = 0x0,
PLD_Reference = 0x0,
PLD_Rotation = 0x0,
PLD_Order = 0x0,
PLD_VerticalOffset = 0xFFFF,
PLD_HorizontalOffset = 0xFFFF)
})
}
Device (PRT2)
{
Name (_ADR, 0x02) // _ADR: Address
Name (_UPC, Package (0x04) // _UPC: USB Port Capabilities
{
0xFF,
0x03,
Zero,
Zero
})
Name (_PLD, Package (0x01) // _PLD: Physical Location of Device
{
ToPLD (
PLD_Revision = 0x2,
PLD_IgnoreColor = 0x1,
PLD_Red = 0x0,
PLD_Green = 0x0,
PLD_Blue = 0x0,
PLD_Width = 0x0,
PLD_Height = 0x0,
PLD_UserVisible = 0x1,
PLD_Dock = 0x0,
PLD_Lid = 0x0,
PLD_Panel = "BACK",
PLD_VerticalPosition = "CENTER",
PLD_HorizontalPosition = "RIGHT",
PLD_Shape = "VERTICALRECTANGLE",
PLD_GroupOrientation = 0x0,
PLD_GroupToken = 0x0,
PLD_GroupPosition = 0x2,
PLD_Bay = 0x0,
PLD_Ejectable = 0x1,
PLD_EjectRequired = 0x0,
PLD_CabinetNumber = 0x0,
PLD_CardCageNumber = 0x0,
PLD_Reference = 0x0,
PLD_Rotation = 0x0,
PLD_Order = 0x0,
PLD_VerticalOffset = 0xFFFF,
PLD_HorizontalOffset = 0xFFFF)
})
}
...
There was a problem hiding this comment.
Blocking the original OEM SSDT table for the USB works on our end, the _STA is not necessary
AMD is not supported in this guide, nor laptops since you have to edit the DSDT.
There was a problem hiding this comment.
It is feasible - but every other part of the guide who says "Do not inject your DSDT" has to be updated
There was a problem hiding this comment.
It is feasible - but every other part of the guide who says "Do not inject your DSDT" has to be updated
Or you can _STA the old root hub and create a new one in an SSDT, as I mentioned above. This would also avoid having to drop any tables and would generally be easier for end users.
There was a problem hiding this comment.
@dhinakg Hello, I am AMD notebook, there are two buses xhc0 and xhc1, xhc1 must be turned off to enter the system, I saw the above document can customize DSDT, can this method solve the problem of not closing xhc1
usb/manual/ssdt.md
Outdated
|
|
||
| A little bit of history worth to mention: | ||
|
|
||
| * Thanks to [Gengik84](https://www.macos86.it/profile/1-gengik84/) and the [macos86.it community](https://www.macos86.it/topic/9-mappatura-porte-usb/) for developing and testing this quick and easy method, the original post dates back to 2018, even though some folks [stole it later in 2019](https://www.olarila.com/topic/6181-guide-native-usb-fix-for-desktops-no-injectorkext-required-skylake/) without mentioning any credits. |
There was a problem hiding this comment.
This method of mapping has existed for years, I'm not really sure about attributing all the credit to Gengik84/macos86.it for it (although make no mistake, I'm not trying to diminish their contributions or anything). The stolen remark is also useless and will just lead to more traffic, there is no point in including it.
There was a problem hiding this comment.
The "quick and easy method" I was talking about in the guide referred to the Method itself described in the .txt - not the port naming itself, such as 0x03 for external USB 3.0 or 0x00 for 2.0 - which was defined in ACPI spec
This method of mapping has existed for years
I cannot find the GENG method anywhere else except in those websites who stole it, please post where this method was reported before the creator wrote it
will just lead to more traffic
This is true, but
The stolen remark is also useless
this was my way to make it clear that others often steal what you do and they sell it as their own effort - that's very sick with open source. For the scope of the guide it is indeed useless, but developers are people too and not robots, hence it was worth on my end to mention why the guide came so much later from its creation in 2018
There was a problem hiding this comment.
Mapping through ACPI has existed for years:
https://www.insanelymac.com/forum/topic/253502-dsdt-fix-for-usb2/
https://www.insanelymac.com/forum/topic/323540-thunderbolt-drivers/
https://www.insanelymac.com/forum/topic/215986-kind-of-dsdt-fix-for-usb-device-dead-after-wake-from-sleep-on-1063/
https://www.insanelymac.com/forum/topic/334203-ssdt-high-sierra-native-usb-on-ryzen-without-genericusbxhci-or-injector-kexts/
Mapping through ACPI is not new, nor using a method to reduce repetition in _UPC/_PLD.
I get how you feel about having the guide stolen, but for the end-user all that will happen is that they will go to the other guide and potentially use it.
There was a problem hiding this comment.
Maybe I wasn't clear enough...
I'm talking about the single Method to map all the ports, not the _UPC/PLD
The method GENG was stolen by Maldon and renamed to MALD in here:
https://www.olarila.com/topic/6181-guide-native-usb-fix-for-desktops-no-injectorkext-required-skylake/
There was a problem hiding this comment.
By the way I removed the maldon part in the guide. Now the credits are there for the uniqueMethod only to define both the ports and the connectors - which has never existed, even in the links you forwarded
There was a problem hiding this comment.
The source for the GENG method is the motherboard ACPI writers themselves, who have sourced it from Intel's internal dev kits. For example, said GENG method is identical to one found in my DSDT:
Method (UUPC, 2, Serialized)
{
Name (PCKG, Package (0x04)
{
Zero,
0xFF,
Zero,
Zero
})
PCKG [Zero] = Arg0
PCKG [One] = Arg1
Return (PCKG) /* \_SB_.PCI0.XHC_.RHUB.UUPC.PCKG */
}
Vendors have been doing this for a while, this is not new by any means.
There was a problem hiding this comment.
Vendors have been doing this for a while, this is not new by any means.
I could not find any firmware made before the beginning of 2018 implementing this, please provide more examples where that method was present even previously
There was a problem hiding this comment.
But after all, are there any issues in mentioning someone's work in the credits?
There was a problem hiding this comment.
I could not find any firmware made before the beginning of 2018 implementing this, please provide more examples where that method was present even previously
@1alessandro1 Both my MSI Z170A and my HP Elite X2 have this method used for their RHUB devices, which are both Skylake series devices. Again, looking even at the Intel Skylake developer kit leaks, we can see this is even used by intel themselves
|
|
||
| ## Adding the method to the original SSDT | ||
|
|
||
| Let's start by adding the `GENG` method that can be found in MaciASL's Patch menu or this [link](https://github.com/1alessandro1/OpenCore-Post-Install/blob/master/extra-files/UsbConnectorTypePatch.txt) copy all those lines present in the .txt to the clipboard. |
There was a problem hiding this comment.
This needs to be adjusted to cover if it's the DSDT, and adjust the controller path in the patch.
There was a problem hiding this comment.
For now dortania does not recommend to inject a custom DSDT everywhere in the guides, so I omitted that part
There was a problem hiding this comment.
@1alessandro1 We do not mean inject a new DSDT, but handle cases where the maps are in the DSDT. ie. disable the RHUB defined in the DSDT and rebuild it in a new custom SSDT
For reference, my X299 board has 1 XHCI controller defined in the DSDT and 2 other XHCI controllers handled in SSDTs. Simply disabling the RHUB for all 3 and rebuilding would allow you to have 1 big map. This would also allow you to not drop SSDTs as well
There was a problem hiding this comment.
@khronokernel feel free to contribute in this PR or make a new PR from my fork with the RHUB method, but I find it a little bit awkward.
Or somebody can contribute to add a specific part for HEDT which requires special treatment later on
There was a problem hiding this comment.
@1alessandro1 This is not just an HEDT issue, this affect standard desktops as well as laptops. Yes you prefixed saying you don't support laptops however that's a big issue you're omiting by not mentioning it.
Regarding adapting, we mainly discussed supporting this PR specifically as we couldn't justify adjusting the guide for SSDT mapping ourselves . From our perspective, the PR as-is is not something we'd want to merge into dortania, we'd prefer a wider scope guide that can handle more cases as it is possible and fairly trivial to accomplish.
If you're not interested, you can simply mark this PR as a draft and leave it for a bit for someone else to pick up
There was a problem hiding this comment.
Goodmoring @khronokernel and @dhinakg, yesterday evening we and @dreamwhite found a clever way to map usb ports present in the DSDT without having to drop tables or having to load SSDT-RHUB mentioned above.
Basically by hot patching the _UPC method to XUPC we managed to define that method in an external SSDT-USB, like this one attached below.
Let us know your opinions.
Archive.zip
There was a problem hiding this comment.
Here's a demonstration from ioreg, where HS01 (originally defined as 0xff) is now correctly named as 0x03 since that port is a 3.0 port with retrocompatible USB 2.0 personality
There was a problem hiding this comment.
Here instead is an ACPI log extracted from dmesg with those hotpatches plus the custom SSDT table, as you can see, there are no errors related to USB and such
There was a problem hiding this comment.
Patches are generally iffy to begin with and we don't recommend using them if they're not needed. Writing generic patches is incredibly hard to do as due to how AML works, it's not always something you can take care of with a simple find and replace. For example, _OSI to XOSI can match against SB.OSIN, although we consider it a necessary evil as there hasn't any good option (currently, we're actively exploring options) that also isn't too complicated for most users.
To take this specific patch as an example, it will match to _UPC followed by a null byte, but it could also match to _.UPC followed by a null byte. Although this looks invalid (as names are padded with underscores so that they will always be four characters, and the above is three), you have to take into account AML opcodes that may raise issues.
In addition to this, we also know that many firmwares have had a bad track record at being compliant to the ACPI spec. If a firmware defines a _UPC method for other purposes and gets XUPC instead, anywhere it is referenced in the ACPI will error + anything external (although unlikely) that is expecting _UPC will also error.
For these reasons, we'd like to avoid patches when possible.
Even if patches were not a mess though, the implementation has some problems:
- This patch assumes MethodFlags are always 0. Adjusting the patch to use a mask would result in it potentially matching other names.
- If you don't include MethodFlags in find, then you would have to add bytes to the left to restrict matches, and PkgLength is of variable length.
Also this method of SSDT mapping has inherent problems in itself that I have realized today: any port that is special cased is going to be a mess. For example, if a port's definition is wrapped in if statements, that is going to suddenly make the SSDT more clunky. The "recreating RHUB" method does avoid this, however. Why not do this instead?
Due to this, we'd like to stick with kext mapping for now, as it has much less drawbacks and different casing that mapping via an SSDT. We expect to have major changes in USB mapping soon anyway that will require a rewrite, or at least major changes.
There was a problem hiding this comment.
Patches are generally iffy to begin with and we don't recommend using them if they're not needed. Writing generic patches is incredibly hard to do as due to how AML works, it's not always something you can take care of with a simple find and replace. For example, _OSI to XOSI can match against SB.OSIN, although we consider it a necessary evil as there hasn't any good option (currently, we're actively exploring options) that also isn't too complicated for most users.
To take this specific patch as an example, it will match to
_UPCfollowed by a null byte, but it could also match to_.UPCfollowed by a null byte. Although this looks invalid (as names are padded with underscores so that they will always be four characters, and the above is three), you have to take into account AML opcodes that may raise issues.In addition to this, we also know that many firmwares have had a bad track record at being compliant to the ACPI spec. If a firmware defines a _UPC method for other purposes and gets XUPC instead, anywhere it is referenced in the ACPI will error + anything external (although unlikely) that is expecting _UPC will also error.
Dear @dhinakg good morning. first of all thank you so much for replying us. I perfectly got your point regarding the _UPC method invalidation but I have a few doubts that some firmwares may use _UPC for other purposes.
At least, according to Section 9.14 of ACPI Specification manual this method, despite is optional, is necessary for specifying custom USB Port Capabilites. Eventually may you gently provide some resources of monkey-written firmwares so we can try to adjust the patching mechanism?
1. This patch assumes MethodFlags are always 0. Adjusting the patch to use a mask would result in it potentially matching other names.
Regarding this point, I've thought about it these days and probably this entire PR should be moved onto Getting Started with ACPI or at least must have a section on it which explains why we should use some ACPI patches and how to obtain them and how to be sure that only the wanted stuff gets patched (you know, you add a Find pattern which must match only one thing. How to be sure about that? Open up DSDT.aml using Hex Fiend and look for the pattern).
Probably, you'd like that first dortania's bugtracker issue #9 gets completed, then we can start talking about ACPI renames. Don't you think so?
If yes, I want you to notice that I'm """writing""" a guide for patching the battery fields, both via static-patching (using DSDT.aml) and hot-patching (by using a blank SSDT-BATT.aml), and the hot-patching criteria is always the same. Let me know whether you're interested and eventually we may discuss on that later.
Also this method of SSDT mapping has inherent problems in itself that I have realized today: any port that is special cased is going to be a mess. For example, if a port's definition is wrapped in if statements, that is going to suddenly make the SSDT more clunky.
I'm feeling a little bit confused about this statement. I mean, are you talking about the depicted below picture?
If yes, from what I've experienced by patching USB using the OEM SSDT Method (e.g. xh_rvp08), theorically there's no need to worry about that especially if we can first confirm that each port is working (or at least detected) without mapping. Then we can just specify the _UPC method for each port as I did with @1alessandro1's custom USB SSDT.
If no, gently can you explain me better what are you talking about then? 😅
Due to this, we'd like to stick with kext mapping for now, as it has much less drawbacks and different casing that mapping via an SSDT. We expect to have major changes in USB mapping soon anyway that will require a rewrite, or at least major changes.
That's a fair point but if so, why does @corpnewt in his USBMap README.md states that the kext approach is less clean than the ACPI method? Can you please give more detailed information about that?
We can actually leverage this template to create our own injector kext that maps the ports on our motherboard! This is the approach we'll use for this guide, and the approach that USBMap uses.
Pros:
- Uses the same approach Apple does
- No extra code to execute
- Can be mostly automated
Cons:
- May not always be Apple's approach
- Not as clean as an ACPI-only solution
Anyways, despite this topic is still hot and must have more attention on what we write and how we write, as this may lead users to confusion, I'd want to thank you for your patience and for your time.
So do I expect having major changes in USB mapping soon, so we can at least have more clarity on this topic.
Again, thank you so much and have a nice day
This guide adds support for SSDT USB mapping.
Credits are very important here since this guide has already been stolen in the past, and I'd like to know what's @khronokernel opinion on those references.
Images and links to the patch can be adjusted later, once the patch is merged in the MaciASL patch menu, and the guide will be updated