- Joined
- Apr 5, 2016
- Messages
- 959
- Motherboard
- GIGABYTE Z170X-Gaming 7
- CPU
- i7-6700K
- Graphics
- GTX TITAN X
- Mac
- Classic Mac
- Mobile Phone
This thread relates to a crash that may occur in Mac OS X El Capitan 10.11.x or earlier with some motherboards that have a serial port. This is no longer an issue with macOS Sierra 10.12.x.
I have my serial port working in Mac OS X, and I am posting here my experience with that.
Many guides say to disable Serial Port 1 in Super IO Configuration without explaining why. I believe it is because of a kernel panic that may occur at startup (which I have experienced and fixed).
What is the serial port?
The Z170X Gigabyte Gaming 7 motherboard uses the IT8628E
The iTE® Super I/O has a 16C550 UART.
In Windows, the COM1 port is at path ACPI\PNP0501\0
Vendor is PNP, device is 0501 (actually PNP is not a vendor; it's used for devices that don't have a EISA ID or defines a compatibility device)
BIOS device name \_SB.PCI0.LPCB.UAR1
LPCB = LPC Bus = Low Pin Count Bus
UAR = UART = universal asynchronous receiver/transmitter
Asynchronous means there is no shared clock between devices (they have to agree on a bit rate) and some form of data framing is required. In the case of RS-232, RS-422, etc., this means a start bit and one or more stop bits. A digital phase locked loop is used to get the timing of received bits.
Old Macs with a mini-DIN 8 connector used a 85C30 SCC (serial controller chip) which have both asynchronous and synchronous modes and allowed external clocking.
What does disabling the serial port do?
Changing the "SuperIO (Serial)" setting in BIOS appears to change bit 0 of IOST in the DSDT. A value of 0 means the serial port is disabled. The value is checked by the UAR1 _STA method (Status). If the status method result is disabled, then the UAR1 device will not appear in Mac OS X's IORegistry and a driver can't match or attach to it.
How is the Mac OS X serial driver supposed to work?
The Mac OS X driver for the COM port is Apple16X50ACPI.kext which is inside of Apple16X50Serial.kext as a plugin. I'm not sure how plugins work... Here's what I mean:
Apple16X50ACPI.kext matches against ACPI device (IOACPIPlatformDevice) PNP0501 (IONameMatch) and has a dependency (OSBundleLibraries) on com.apple.driver.Apple16X50Serial but that exists only in Apple16X50Serial.kext which matches against PCI serial communications cards (IOPCIClassMatch). So if I have no PCI serial communications card, how does Apple16X50ACPI.kext load?
Q: If Apple16X50Serial.kext is not in /S*/L/*/E, and there is no PCI serial communications card, what command in Terminal.app will load the Apple16X50ACPI.kext?
Anyway, you don't need to worry about that since it loads anyway during the boot process.
What is the problem?
Apple16X50ACPI.kext attaches to UAR1 as Apple16X50ACPI0 with IOTTYSuffix = 0 because the _UID of UAR1 is 0. Then a com_apple_driver_16X50UARTSync is attached with the same IOTTYSuffix. At this point you would expect a IOSerialBSDClient to be attached to that (IOProbeScore = 1000).
The problem is that IOBluetoothHostControllerUARTTransport attaches instead (IOPropertyMatch on IOTTYSuffix = 0) because IOProbeScore is higher (2000). The 16C550 is not a bluetooth UART so a kernel panic may occur.
Solutions
Skip to the bottom to see my best solution.
I have my serial port working in Mac OS X, and I am posting here my experience with that.
Many guides say to disable Serial Port 1 in Super IO Configuration without explaining why. I believe it is because of a kernel panic that may occur at startup (which I have experienced and fixed).
What is the serial port?
The Z170X Gigabyte Gaming 7 motherboard uses the IT8628E
The iTE® Super I/O has a 16C550 UART.
In Windows, the COM1 port is at path ACPI\PNP0501\0
Vendor is PNP, device is 0501 (actually PNP is not a vendor; it's used for devices that don't have a EISA ID or defines a compatibility device)
BIOS device name \_SB.PCI0.LPCB.UAR1
LPCB = LPC Bus = Low Pin Count Bus
UAR = UART = universal asynchronous receiver/transmitter
Asynchronous means there is no shared clock between devices (they have to agree on a bit rate) and some form of data framing is required. In the case of RS-232, RS-422, etc., this means a start bit and one or more stop bits. A digital phase locked loop is used to get the timing of received bits.
Old Macs with a mini-DIN 8 connector used a 85C30 SCC (serial controller chip) which have both asynchronous and synchronous modes and allowed external clocking.
What does disabling the serial port do?
Changing the "SuperIO (Serial)" setting in BIOS appears to change bit 0 of IOST in the DSDT. A value of 0 means the serial port is disabled. The value is checked by the UAR1 _STA method (Status). If the status method result is disabled, then the UAR1 device will not appear in Mac OS X's IORegistry and a driver can't match or attach to it.
How is the Mac OS X serial driver supposed to work?
The Mac OS X driver for the COM port is Apple16X50ACPI.kext which is inside of Apple16X50Serial.kext as a plugin. I'm not sure how plugins work... Here's what I mean:
Apple16X50ACPI.kext matches against ACPI device (IOACPIPlatformDevice) PNP0501 (IONameMatch) and has a dependency (OSBundleLibraries) on com.apple.driver.Apple16X50Serial but that exists only in Apple16X50Serial.kext which matches against PCI serial communications cards (IOPCIClassMatch). So if I have no PCI serial communications card, how does Apple16X50ACPI.kext load?
Q: If Apple16X50Serial.kext is not in /S*/L/*/E, and there is no PCI serial communications card, what command in Terminal.app will load the Apple16X50ACPI.kext?
Anyway, you don't need to worry about that since it loads anyway during the boot process.
What is the problem?
Apple16X50ACPI.kext attaches to UAR1 as Apple16X50ACPI0 with IOTTYSuffix = 0 because the _UID of UAR1 is 0. Then a com_apple_driver_16X50UARTSync is attached with the same IOTTYSuffix. At this point you would expect a IOSerialBSDClient to be attached to that (IOProbeScore = 1000).
The problem is that IOBluetoothHostControllerUARTTransport attaches instead (IOPropertyMatch on IOTTYSuffix = 0) because IOProbeScore is higher (2000). The 16C550 is not a bluetooth UART so a kernel panic may occur.
Solutions
Skip to the bottom to see my best solution.
- Disable the serial port using BIOS.
But if you want to use the serial port in Windows then you have to go back into BIOS.
Also, if you set BIOS settings to default, you might have to change the setting again before booting Mac OS X.
- Disable the serial port in Clover by setting IOST = 0
But this solution is specific to BIOSs that use that to disable UAR1. Also the other bits of IOST are used for other settings. In the DSDT there is a line like this:Use "iasl -l" to disassemble your DSDT, find the bytes that set IOST to 0001, then add to config.plist/ACPI/DSDT/Patches to replace those bytes with bytes that will set IOST to 0000.Code:Name (IOST, 0x0001)
- Disable the serial port in Clover by removing device UAR1
Use the same kind of patch as above. Or maybe create an SSDT to do it.
- Remove IOBluetoothHostControllerUARTTransport.kext from S/L/E
This might mess up future software updates.
This might disable some Bluetooth controllers.
This only works on OS's that you modify.
This is difficult to do in the Mac OS X installer since it uses a disk image.
Q: What Bluetooth controllers require IOBluetoothHostControllerUARTTransport?
- Remove IOBluetoothHostControllerUARTTransport.kext using Clover
But this might disable some Bluetooth controllers.
Anyway, I don't think Clover has an option to drop a kext.
- Use Clover to make IOBluetoothHostControllerUARTTransport.kext not match IOTTYSuffix 0
There are ways to add IOKitPersonalities (see next) but I don't know how to remove a personality. This might disable some Bluetooth controllers.
You can add a kext patch to Clover to modify IOBluetoothHostControllerUARTTransport.kext. However, that might not work if the kext is not cached correctly or if the kext changes in the future (which is probably not an issue since macOS no longer has this problem).
- Make IOBluetoothHostControllerUARTTransport not match by creating a IOSerialBSDClient with a higher IOProbeScore
This only requires an info.plist in a new kext. The new kext can be put in Clover kexts.
Code:find Apple16X50SerialBSDClientSync.kextApple16X50SerialBSDClientSync.kext Apple16X50SerialBSDClientSync.kext/Contents Apple16X50SerialBSDClientSync.kext/Contents/Info.plist cat Apple16X50SerialBSDClientSync.kext/Contents/Info.plist <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>CFBundleDevelopmentRegion</key> <string>English</string> <key>CFBundleIdentifier</key> <string>com.apple.Apple16X50SerialBSDClientSync</string> <key>CFBundleInfoDictionaryVersion</key> <string>6.0</string> <key>CFBundleName</key> <string>SerialBSDClient for 16X50 Serial Port</string> <key>CFBundlePackageType</key> <string>KEXT</string> <key>CFBundleShortVersionString</key> <string>1</string> <key>CFBundleSignature</key> <string>????</string> <key>CFBundleVersion</key> <string>1</string> <key>IOKitPersonalities</key> <dict> <key>IOSerialBSDClientSync</key> <dict> <key>CFBundleIdentifier</key> <string>com.apple.iokit.IOSerialFamily</string> <key>IOClass</key> <string>IOSerialBSDClient</string> <key>IOProbeScore</key> <integer>2001</integer> <key>IOPropertyMatch</key> <dict> <key>CFBundleIdentifier</key> <string>com.apple.driver.Apple16X50ACPI</string> <key>IOTTYSuffix</key> <string>0</string> </dict> <key>IOProviderClass</key> <string>IOSerialStreamSync</string> <key>IOResourceMatch</key> <string>IOBSD</string> </dict> </dict> <key>OSBundleRequired</key> <string>Safe Boot</string> </dict> </plist>
It stops IOBluetoothHostControllerUARTTransport from attaching but doesn't stop it from loading it's classes. This conflicts with IOBluetoothHostControllerUSBTransport (I have a USB bluetooth dongle connected) because they both declare the IOBluetoothHostControllerTransport class. During boot and after the finder loads, I see an infinite loop of attempts to load IOBluetoothHostControllerUSBTransport (one or two attempts every second). I'm using RRehabMan's OS-X-BrcmPatchRAM for my USB Bluetooth dongle. I'm not sure if that is part of the problem.
- Recompile the Apple16X50Serial project so that IOTTYSuffix is not 0
This is the method I'm currently using. I downloaded the source, replaced all occurrences of Apple16X50 with Hack16X50 (including file names), increased the IOProbeScore of Hack16X50ACPI to 1001, and added the source files from the Hack16X50Serial target to the Hack16X50ACPI target so that Hack16X50Serial.kext doesn't need to be loaded, changed method start of Hack16X50ACPI to always call startUARTs with true which eliminates IOTTYSuffix for the first UART.
The problem with this is that the source from Apple may not be the latest (Apple16X50Serial-24 has version 3.0 but Mac OS X 10.11.4 has version 3.2). Also, this may break some setups (if there are other 16X50 UARTs which can be added by PC Card or whatever) so additional code may be needed to handle all the possibilities.
- Use Clover to patch Apple16X50ACPI so that IOTTYSuffix is not 0
This would be better than the above because it means the latest code would be used but this would require disassembling the kext to figure out what needs to change, and the required changes might be too complicated and, as above, might break some setups. Also, if the kext changes in the future then the patch might not get applied (which is probably not an issue since macOS no longer has this problem).
- Use Clover to modify UAR1 so that Apple16X50ACPI chooses not to set IOTTYSuffix to 0
I believe this would the best solution. Looking at the start method of Apple16X50ACPI, you can see that if there's a "AAPL,connector" property set to "DB9", then the IOTTYSuffix will not be set for the first UART of the device. Adding this property to one device will not affect the driver's behavior with other devices, unlike the previous two solutions (but even those solutions could be made to do the same as this if they have the added code to check what device they are affecting).
Clover doesn't support adding properties to ACPI devices that are not PCI devices, so you would have to patch the DSDT or add an SSDT.
Rather than add a "AAPL,connector" property, it may be simpler to alter the _UID with a DSDT patch.
Use MacIASL.app to grab the ACPI tables into a .acpi file, then use the following commands to extract and disassemble them.
Code:cd /Volumes/joevt/Documents mkdir "Joe’s Giga Mac F20 serial tables" cd "Joe’s Giga Mac F20 serial tables" eval $(plutil -p "../Joe’s Giga Mac F20 serial.acpi" | sed -En '/^ *"([^"]+)" => <([^>]+)>/s//echo -n "\2" | xxd -r -p > "\1.aml";/p') ~/src/opt/local/bin/iasl -l -d * grep -r UAR1 .
Find the serial port device and copy the bytes you want to change. Below is the result of the disassembly for my BIOS (yours may be different). You'll want to search for any device with name (HID) of "PNP0501". It's possible other devices may cause IOTTYSuffix to be 0, but we only know for sure that it happens with "PNP0501" devices.
We want to change _UID from 0 to something else so make sure the bytes to change includes the part that defines _UID.
Code:Device (UAR1) { 46FF: 5B 82 46 0C 55 41 52 31 // [.F.UAR1 Name (_HID, EisaId ("PNP0501") /* 16550A-compatible COM Serial Port */) // _HID: Hardware ID 4707: 08 5F 48 49 44 0C 41 D0 05 01 // ._HID.A... Name (_UID, Zero) // _UID: Unique ID 4711: 08 5F 55 49 44 00 // ._UID.
You'll want to skip the bytes "46 OC" since that's the PkgLength for the DefDevice of UAR1 (read the "ACPI Machine Language (AML) Specification" section in the ACPI 6.1 specification pdf). The PkgLength will change in future BIOS versions if more code is added to the device. The PkgLength will change after the patch if you choose to use a UID greater than 1 (since numbers greater than 1 require more than one byte to encode), or if the device doesn't define a UID and you want to make a patch that defines UID.
Convert the bytes you want to search for into base64 so you can paste them into config.plist.
Code:echo "55 41 52 31 08 5F 48 49 44 0C 41 D0 05 01 08 5F 55 49 44 00" | xxd -p -r | base64
Write some AML code that looks like the original, with the change you want to make. The new _UID should be unique from all other serial ports (I chose 1234 in this example). Use iasl to assemble it and create a listing file to get the bytes:
Code:echo ' DefinitionBlock ("PNP0501_UID_fix.aml", "DSDT", 1, "OEM_ID", "OEMTABLE", 0x00010001){ Device (UAR1) { Name (_HID, EisaId ("PNP0501")) Name (_UID, 1234) } } ' > /tmp/PNP0501_UID_fix.asl ~/src/opt/local/bin/iasl -l /tmp/PNP0501_UID_fix.asl cat /tmp/PNP0501_UID_fix.lst
The result in the lst file looks like this:
Code:3: Device (UAR1) 00000024: 5B 82 17 55 41 52 31 ... "[..UAR1" 4: { 5: Name (_HID, EisaId ("PNP0501")) 0000002B: 08 5F 48 49 44 0C 41 D0 "._HID.A." 00000033: 05 01 .................. ".." 6: Name (_UID, 1234) 00000035: 08 5F 55 49 44 0B D2 04 "._UID..."
Convert the bytes you want to replace with into base64 so you can paste them into config.plist:
Code:echo "55 41 52 31 08 5F 48 49 44 0C 41 D0 05 01 08 5F 55 49 44 0B D2 04" | xxd -p -r | base64
This is the patch to be placed into config.plist under ACPI/DSDT/Patches/:
Code:<dict> <key>Comment</key><string>UAR1 UID:0->1 stops El Capitan serial port/bluetooth crash on Gigabyte Gaming 7 motherboard</string> <key>Find</key> <data>VUFSMQhfSElEDEHQBQEIX1VJRAA=</data> <key>Replace</key><data>VUFSMQhfSElEDEHQBQEIX1VJRAvSBA==</data> </dict>
Notice that the replace bytes is longer than the find bytes because 1234 takes 3 bytes to encode, and 0 takes only 1 byte to encode. Clover is smart enough to update the PkgLength of all enclosing objects in the DSDT.
Last edited:
