Skip to content

Instantly share code, notes, and snippets.

@MadLittleMods
Last active April 3, 2024 06:49
Show Gist options
  • Save MadLittleMods/3005bb13f7e7178e1eaa9f054cc547b0 to your computer and use it in GitHub Desktop.
Save MadLittleMods/3005bb13f7e7178e1eaa9f054cc547b0 to your computer and use it in GitHub Desktop.

Realtek 8153

Download

Current version: 1.0.19 1.0.15 (as of 2018-12-10)

https://www.realtek.com/en/component/zoo/category/network-interface-controllers-10-100-1000m-gigabit-ethernet-usb-3-0-software

http://www.realtek.com.tw/downloads/downloadsView.aspx?Langid=1&PNid=13&PFid=56&Level=5&Conn=4&DownTypeID=3&GetDown=false

Realtek GBE USB

  • Gigabit ethernet
  • USB hub

Gather Info




  • Launch a terminal/shell
  • ioreg -p IOUSB -w0
  • ioreg -p IOUSB -w0 -l: For more info
+-o Root  <class IORegistryEntry, id 0x100000100, retain 14>
  +-o Root Hub Simulation Simulation@14000000  <class AppleUSBRootHubDevice, id 0x1000002fa, registered, matched, active, busy 0 (6 ms), retain 13>
    +-o USB2.0 Hub             @14100000  <class AppleUSBDevice, id 0x1000002fb, registered, matched, active, busy 0 (43 ms), retain 14>
    +-o Apple Internal Keyboard / Trackpad@14400000  <class AppleUSBDevice, id 0x1000002ff, registered, matched, active, busy 0 (96 ms), retain 22>
    +-o USB3.0 Hub             @14500000  <class AppleUSBDevice, id 0x100000363, registered, matched, active, busy 0 (54 ms), retain 15>
    | +-o USB 10/100/1000 LAN@14540000  <class AppleUSBDevice, id 0x100000418, registered, matched, active, busy 0 (73 ms), retain 18>
    +-o Bluetooth USB Host Controller@14300000  <class AppleUSBDevice, id 0x1000003d8, registered, matched, active, busy 0 (58 ms), retain 24>
Terminal output snippet from `ioreg -p IOUSB -w0 -l`
+-o USB3.0 Hub             @14500000  <class AppleUSBDevice, id 0x100000363, registered, matched, active, busy 0 (54 ms), retain 15>
    | | {
    | |   "sessionID" = 2480892594
    | |   "iManufacturer" = 1
    | |   "bNumConfigurations" = 1
    | |   "idProduct" = 2066
    | |   "bcdDevice" = 37009
    | |   "Bus Power Available" = 900
    | |   "USB Address" = 5
    | |   "bMaxPacketSize0" = 9
    | |   "iProduct" = 2
    | |   "iSerialNumber" = 0
    | |   "bDeviceClass" = 9
    | |   "Built-In" = No
    | |   "locationID" = 340787200
    | |   "bDeviceSubClass" = 0
    | |   "bcdUSB" = 768
    | |   "USB Product Name" = "USB3.0 Hub             "
    | |   "PortNum" = 5
    | |   "non-removable" = "no"
    | |   "IOCFPlugInTypes" = {"9dc7b780-9ec0-11d4-a54f-000a27052861"="IOUSBFamily.kext/Contents/PlugIns/IOUSBLib.bundle"}
    | |   "bDeviceProtocol" = 3
    | |   "IOUserClientClass" = "IOUSBDeviceUserClientV2"
    | |   "IOPowerManagement" = {"DevicePowerState"=0,"CurrentPowerState"=3,"CapabilityFlags"=65536,"MaxPowerState"=4,"DriverPowerState"=3}
    | |   "Device Speed" = 3
    | |   "USB Vendor Name" = "VIA Labs, Inc.         "
    | |   "idVendor" = 8457
    | |   "IOGeneralInterest" = "IOCommand is not serializable"
    | |   "IOClassNameOverride" = "IOUSBDevice"
    | | }
    | |
    | +-o USB 10/100/1000 LAN@14540000  <class AppleUSBDevice, id 0x100000418, registered, matched, active, busy 0 (73 ms), retain 18>
    |     {
    |       "sessionID" = 3379212797
    |       "iManufacturer" = 1
    |       "bNumConfigurations" = 2
    |       "idProduct" = 33107
    |       "bcdDevice" = 12288
    |       "Bus Power Available" = 900
    |       "USB Address" = 8
    |       "bMaxPacketSize0" = 9
    |       "iProduct" = 2
    |       "iSerialNumber" = 3
    |       "bDeviceClass" = 0
    |       "Built-In" = No
    |       "locationID" = 341049344
    |       "bDeviceSubClass" = 0
    |       "bcdUSB" = 768
    |       "USB Product Name" = "USB 10/100/1000 LAN"
    |       "PortNum" = 4
    |       "non-removable" = "no"
    |       "IOCFPlugInTypes" = {"9dc7b780-9ec0-11d4-a54f-000a27052861"="IOUSBFamily.kext/Contents/PlugIns/IOUSBLib.bundle"}
    |       "bDeviceProtocol" = 0
    |       "IOUserClientClass" = "IOUSBDeviceUserClientV2"
    |       "IOPowerManagement" = {"ChildrenPowerState"=4,"DevicePowerState"=0,"CurrentPowerState"=4,"CapabilityFlags"=32768,"MaxPowerState"=4,"DriverPowerState"=4}
    |       "Device Speed" = 3
    |       "USB Vendor Name" = "Realtek"
    |       "idVendor" = 3034
    |       "IOGeneralInterest" = "IOCommand is not serializable"
    |       "USB Serial Number" = "002427FE48F6"
    |       "IOClassNameOverride" = "IOUSBDevice"
    |     }
    |

  • Launch a terminal/shell
  • ifconfig
en4: flags=8863<UP,BROADCAST,SMART,RUNNING,SIMPLEX,MULTICAST> mtu 1500
	options=2b<RXCSUM,TXCSUM,VLAN_HWTAGGING,TSO4>
	ether 00:24:27:fe:48:f6
	inet 192.168.1.135 netmask 0xffffff00 broadcast 192.168.1.255
	media: autoselect (1000baseT <full-duplex,flow-control>)
	status: active

Reload OSX driver (kext)

The driver is located at

  • /System/Library/Extensions/IONetworkingFamily.kext/Contents/PlugIns/AppleRTL815X*.kext
  • /Library/Extensions/AppleRTL815X*.kext

Here are the namespaces:

  • com.realtek.driver.AppleRTL815XEthernet
  • com.realtek.driver.AppleRTL815XComposite

See http://osxdaily.com/2015/06/24/load-unload-kernel-extensions-mac-os-x/

With normal operation with only the network cable plugged in, I only see com.realtek.driver.AppleRTL815XEthernet loaded.

# Unload
sudo kextunload /Library/Extensions/AppleRTL815XEthernet109.kext
sudo kextunload /Library/Extensions/AppleRTL815XComposite109.kext

# Load
sudo kextload /Library/Extensions/AppleRTL815XEthernet109.kext
sudo kextload /Library/Extensions/AppleRTL815XComposite109.kext

# Find if loaded
kextstat | grep com.realtek.driver.AppleRTL815XEthernet
kextstat | grep com.realtek.driver.AppleRTL815XComposite

Perhaps clear the Kernel cache

sudo rm -rf /System/Library/Caches/com.apple.kext.caches

I got a new USB ethernet adapter and use the native driver

I got a new USB ethernet adapter because the old one had lots of issues (hence the gist in the first place). But it still uses the same Realtek 8153 chip although am using the native driver though now, AppleUSBECM.kext

In terms of my previous issues, I remember that when I clicked the little lock in the browser to view the cert, it would crash my computer. But the disconnects that required a restart were the bigger issue. (personal reference link)

I'm currently running macOS Mojave 10.14

@zenczykowski
Copy link

Final note: the r8153_ecm linux driver is really just a very minor extension to the standard generic linux cdc ecm driver.
That's why it's just 170 lines (and much of that is boilerplate).

If I'm reading it right, it uses the standard ECM driver for everything, except that it uses a vendor extension for MII - which IFIRC is a way to report (and or configure advertised) link speed/duplex (see https://linux.die.net/man/8/mii-tool ).

The normal Linux ECM driver is normally prevented from binding to an 8153 device, so that the more specific driver will be used instead.

https://github.com/torvalds/linux/blob/master/drivers/net/usb/Kconfig#L637 is pretty crazy.
The lack of a string doc on the tristate line means it is not actually user configurable (there is no build time option to choose whether the driver is enabled or not) - hence the kernel configuration file gets to automatically select whether it should be enabled during build time.

config USB_RTL8153_ECM
tristate
depends on USB_NET_CDCETHER && (USB_RTL8152 || USB_RTL8152=n)
default y

Roughly translates as:

  • define a tristate (No, Module, Yes=built-in) configuration option called USB_RTL8153_ECM, which is not user configurable (via .config).
  • it requires USB_NET_CDCETHER (becomes it's an extension of the CDCETHER, aka ECM driver)
  • it defaults to enabled (y)
    Here stuff gets really finicky.
  • because it depends on USB_NET_CDCETHER, it automatically demotes from 'y' to 'm' if CDCETHER (the ECM driver) is a module.
    (you can't have the driver extension be built into the kernel, if the driver it extends isn't built in itself)
    It gets worse:
  • it also depends on (USB_RTL8152 || USB_RTL8152=n) which actually always evaluates to true.
    This is because USB_RTL8152 is either Yes or Module or No.
    Yes and Module make the first half of the || true, while No makes the second half of the || true.
  • okay, so why do this? Because this is actually tristate logic, not normal boolean.
    USB_NET_CDCETHER && (USB_RTL8152 || USB_RTL8152=n)
    has the curious property that USB_NET_CDCETHER=y + USB_RTL8152=m results in the 'default y' being demoted to 'm'.
    (because we're depending on a module)
    Why do this? Because if you build the ECM driver into the kernel, and build the 'better' native 8152 driver as a module, you want to be able to easily load the 8152 driver and have it bind to the device, instead of having the built in driver win. This requires the extension to be a module, even though the thing it extends is builtin.
    Basically if both USB_NET_CDCETHER (ie. ECM) and R8153_ECM were builtin, but USB_RTL8152 was a module, the module would never load, since the builtin driver would bind the device when you plug it in.
    Linux does provide a way to manually unbind the built-in driver, and manually bind in the other one, but it's a hassle, and better to just make the extension a module.

This probably still isn't ideal... since I'm not sure what determines which of the 2 drivers wins if both are modular... likely it's random (or alphabetical sort order or something)

@Monstergerm
Copy link

Has anybody noticed dropped outgoing packets as well as Oerrs with the NCM driver?
I have three adapters but only the one using the Realtek 8153 chip set and thus ECM driver does not show these errors. Both 8156 and AX88179A chips using NCM driver have huge percentage of Oerrs (Terminal netstat -di -I en4 command; if your interface is en4).

Name Mtu Network Address Ipkts Ierrs Opkts Oerrs Coll Drop
en4 1500 <Link#26> 00:XX:XX:XX:XX:XX 828846 0 88393 40649 0 9940

@april
Copy link

april commented Oct 26, 2023

That said... there is a rumour of there being an NCM capable 8153 chip... I'm not sure whether it should be believed, or if some manufacturer actually runs a more complex multi-chip setup, or if someone actually developed an NCM capable firmware for the chip, even though [at a cursory glance per the spec sheet] Realtek does not appear to provide one...

The RTL8153D uses the FIRMWARE_8156B_2 firmware, same as the RTL8156B; the Linux driver shows the only difference is that 56B supports 2.5G, while the 53D only does 1G. Presumably the new RTL8153E is NCM as well.

I wrote that Macrumors post about the RTL8156B(S)G, and certainly noticed better performance than the previous chip revisions. This was observed on Linux as well.

@web-xyz
Copy link

web-xyz commented Nov 12, 2023

Has anybody noticed dropped outgoing packets as well as Oerrs with the NCM driver? I have three adapters but only the one using the Realtek 8153 chip set and thus ECM driver does not show these errors. Both 8156 and AX88179A chips using NCM driver have huge percentage of Oerrs (Terminal netstat -di -I en4 command; if your interface is en4).

Name Mtu Network Address Ipkts Ierrs Opkts Oerrs Coll Drop en4 1500 <Link#26> 00:XX:XX:XX:XX:XX 828846 0 88393 40649 0 9940

I have a similar issue with the Belkin USB-C to 2.5 Gb Ethernet Adapter (SKU: INC012btBK) with firmware version 31.04 (so supposedly using RTL8156B(S)G) on a MacBook Pro 16-inch, 2019 with Sonoma 14.1.1: there are Oerrs in the netstat output!

There are no Oerrs with the Thunderbolt to Gigabit Ethernet Adapter (with the Thunderbolt 3 (USB-C) to Thunderbolt 2 Adapter) on the same laptop.

Does everybody with an adapter using RTL8156 / RTL8156B / RTL8156B(S)G have Oerrs?

What do exactly output errors mean and entail?

Any idea on how to fix the issue?

Thanks.

@lcharette
Copy link

lcharette commented Mar 3, 2024

Bit of update as of March 2024 and macOS Sonoma 14.3.1. Look like this is still an issue. Considering business like OWC still sell Thunderbolt dock with the 8156 chipset without any warning about limited capability of the Gigabit port for Mac users, it's a bit frustrating to say the least.

After a bit a of research and trial and error, I found it is possible to achieve gigabit speed on MacOS with the Realtek 8156 chipset, but with a huge caveat, as far as my finding shows : (tl;dr) You need to install the Realtek driver with SIP disabled and keep SIP disabled.

Since this most sources on the Internet point to this Gist, I share below is my process and findings, in case it can help anyone. For my part, I'll most likely be returning the OWC dock and look for a better alternative, as the lack of warning/information from OWC left a bitter taste in my mouth...


As many pointed out, by default, MacOS will use the com.apple.DriverKit.AppleUserECM driver for any Ethernet port passed through USB using the Realtek 8156 chipset. This Apple supplied driver limits the overall speed of Ethernet connection through USB/Thundnerbolt to ~400 Mbps for some reason. The overall solution is to install the official driver from Realtek. However, it hasn't been updated since 2020 and does not appear to be compatible with Apple's new extension privacy feature introduced in Big Sur (11.0). This is why when googling this issue, you'll find a lot of people claiming installing the driver fix the issue, only to realized the comments are probably from 2021.

These are the steps I used on my Intel MacBook Air to get the driver to load, by disabling SIP :

  1. Reboot in Recovery mode : cmd+R
  2. Open Terminal
  3. Disable SIP : csrutil disable
  4. Close Terminal and reboot
  5. Install Realtek Drivers from their website, version 1.0.22 for "MAC OS 10.9 to 10.15". Accept any prompt in system preferences and REBOOT
  6. Plug-in Thunderbolt dock / adapter with 8153 chipset. This is important, as the next step will only be displayed when the adapter is connected. In other words, when you reboot, nothing is loaded. When you connect the adapter, all three extensions listed below will be loaded dynamically and stay loaded until next reboot.
  7. You can make sure com.realtek.driver.AppleRTL815XEthernet extension is loaded from terminal : sudo kmutil showloaded | grep -i realtek. You should see something similar:
$ kmutil showloaded | grep -i realtek
No variant specified, falling back to release
  203    0 0xffffff7f96289000 0xffc      0xffc      com.realtek.driver.AppleRTL815XComposite (1.0.22) BA984F53-C67B-31DB-82FA-9146A9680FCA <74 7 6 3 1>
  204    0 0xffffff8001dbc000 0x7ff4     0x7ff4     com.apple.driver.usb.realtek8153patcher (5.0.0) 1C97FD90-1304-3956-B4D6-272E31074AF6 <30 7 6 3 1>
  205    0 0xffffff7f96235000 0x51ff8    0x51ff8    com.realtek.driver.AppleRTL815XEthernet (1.0.22) E7B07C4A-4CF4-3B58-9027-B592E4A041F3 <119 54 30 7 6 3 1>
  1. System Information (Apple menu > System Settings, then click General in the sidebar. (You may need to scroll down.) Click About on the right, then click System Report) can also tell you which driver your Ethernet connection is currently using. Select "Ethernet" under "Hardware", and select "USB 10/100/1000 LAN". There you should see com.realtek.driver.AppleRTL815XEthernet under "Driver":
2024_03_03_SysInfo_Ethernet_RT110

At this point, everything should be good as you're actually using the Realtek driver and you should be able to run a speed test with ~Gigabit speed, even after a couple of reboots :
2024-03-03_Win

However, remember SIP is currently disabled on you Mac!. To re-enable it :

  1. Reboot in Recovery mode : cmd+R
  2. Open Terminal
  3. Disable SIP : csrutil disable
  4. Close Terminal and reboot

And now, you're back to square one. macOS will revert back to the com.apple.DriverKit.AppleUserECM driver.
2023_03_03_FAIL

SpepedTest_FAIL

$ sudo kmutil showloaded | grep -i realtek
No variant specified, falling back to release
  203    0 0xffffff7f9621d000 0xffc      0xffc      com.realtek.driver.AppleRTL815XComposite (1.0.22) BA984F53-C67B-31DB-82FA-9146A9680FCA <74 7 6 3 1>
  204    0 0xffffff8001dbc000 0x7ff4     0x7ff4     com.apple.driver.usb.realtek8153patcher (5.0.0) 1C97FD90-1304-3956-B4D6-272E31074AF6 <30 7 6 3 1>

I tried manually loading the kext located in /Library/Extensions/ using the Terminal (https://developer.apple.com/documentation/apple-silicon/installing-a-custom-kernel-extension), however the following error is displayed.

$ sudo kextload /Library/Extensions/AppleRTL815XEthernet*.kext

Executing: /usr/bin/kmutil load -p /Library/Extensions/AppleRTL815XEthernet110.kext
Error Domain=KMErrorDomain Code=71 "Unsupported Error: one or more extensions are unsupported to load: 	Kext com.realtek.driver.AppleRTL815XEthernet v1.0.22 in executable kext bundle com.realtek.driver.AppleRTL815XEthernet at /Library/StagedExtensions/Library/Extensions/AppleRTL815XEthernet110.kext" UserInfo={NSLocalizedDescription=Unsupported Error: one or more extensions are unsupported to load: 	Kext com.realtek.driver.AppleRTL815XEthernet v1.0.22 in executable kext bundle com.realtek.driver.AppleRTL815XEthernet at /Library/StagedExtensions/Library/Extensions/AppleRTL815XEthernet110.kext}

Same message with :

$ sudo kmutil clear-staging
$ sudo kmutil load -b com.realtek.driver.AppleRTL815XEthernet

You might even get a System Preference warning telling you the extension is out of date
WarningUpdate

Which is expected under SIP and macOS Sonoma. Disabling SIP and running the same command again does allow the kext to be loaded, and after a confirmation from System Preferences and a reboot, the driver is correctly loaded again. However, SIP is still disabled, so enabling it once again brings you back to square one.

Note that System Information does show the extensions as being present under Software -> Extensions -> AppleRTL815XEthernet110 when SIP is disabled, but still won't use it as a driver :
SysIno_NotLaoded

I believe at this point the driver *is* "installed", but somehow SIP prevent it from being used.

Side note, while @LeuschkeTressa comment was useful to understand the issue, it didn't solve the issue either (and appears to be for another issue altogether).


The most important piece of documentation from Apple can be found here: https://support.apple.com/en-ca/guide/deployment/depa5fb8376f/web

In macOS 11 or later, if third-party kernel extensions (kexts) are enabled, they can’t be loaded into the kernel on demand. They require the user’s approval and restarting of the macOS to load the changes into the kernel, and they also require that the secure boot be configured to Reduced Security on a Mac with Apple silicon.

When a new kext is installed and there’s an attempt to load it, a restart must be initiated by the user from the warning dialog in:

  • macOS 13 or later: Apple menu > System Settings > Privacy & Security.
  • macOS 12.0.1 or earlier: Apple menu > System Preferences, > Security & Privacy.
    This restart initiates the rebuild of the AuxKC before to the kernel booting.

If System Integrity Protection (SIP) is enabled, the signature of each kext is verified before being included in the AuxKC.
If SIP is disabled, the kext signature isn’t enforced.
This approach allows Permissive Security flows for developers or users who aren’t part of the Apple Developer Program to test kexts before they’re signed.

tl;dr Whatever you do, any extension must be approved from System Preference and won't ever be applied until reboot.

I didn't try to Change security settings on the startup disk, since I don't own an Apple Silicon Mac. However, this doesn't sound like a valid solution since you're lowering the security features of your Mac. As Apple mention themselves :

Important: Kexts are no longer recommended for macOS. Kexts risk the integrity and reliability of the operating system. Users should prefer solutions that don’t require extending the kernel and use system extensions instead.

So until Apple themselves fix this or Realtek release updated drivers, stay away from 8153 chipset.

References

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment