New Driver for Realtek RTL8111

[Mieze]

A New Driver for Realtek RTL8111

 

Due to the lack of an OS X driver that makes use of the advanced features of the Realtek RTL81111/8168 series I started a new project with the aim to create a state of the art driver that gets the most out of those NICs which can be found on virtually any cheap board on the market today. Based on Realtek's Linux driver (version 8.035.0) I have written a driver that is optimized for performance while making efficient use of system resources and keeping the CPU usage down under heavy load.

Key Features of the Driver

• Supports Realtek RTL8111/8168 B/C/D/E/F/G/H found on recent boards.
• Support for multisegment packets relieving the network stack of unnecessary copy operations when assembling packets for transmission.
• No-copy receive and transmit. Only small packets are copied on reception because creating a copy is more efficient than allocating a new buffer.
• TCP, UDP and IPv4 checksum offload (receive and transmit).
• TCP segmentation offload under IPv4.
• Support for TCP/IPv6 and UDP/IPv6 checksum offload.
• Fully optimized for Mountain Lion (64bit architecture) but should work with Lion too. As of now there is no support for Snow Leopard but it can be added if someone will create the necessary patches.
• Supports Wake on LAN.
• Support for Energy Efficient Ethernet (EEE) which can be disabled by setting enableEEE to NO in the drivers Info.plist without rebuild. The default is YES.
• The driver is published under GPLv2.

 

Limitations

• As checksum offload doesn't work with jumbo frames they are unsupported up to version 2.3.x. Version 2.4.0 might come with experimental jumbo frame support depending on test results of the development versions.
• No support for 32bit kernels.

 

Installation

• You might want to install the driver to /L/E as usual but it's also ok to use Clover's injection function (installation in the EFI folder).
• Use your favorite kext installation tool for installation or perform the installation manually (for Clover or OC injection). It's your call!

• Reboot
• Open System Preferences again, select Network and check if the new network interface has been created automatically or create it manually now.
• Configure the interface.

 

Help - I'm getting kernel panics!

Well, before you start complaining about bugs after you upgraded macOS and ask me to publish a driver update, you should first try to resolve the issue on your own by cleaning the system caches.

As the driver uses macOS's private network driver interface, which is supposed to be used by Apple provided drivers only, you might run into problems after an OS update because the linker may fail to recognize that IONetworking.kext has been updated and that the driver needs to be linked against the new version (Apple provided drivers avoid this problem because they are always updated together with IONetworking.kext). As a result, the linking process produces garbage and the driver may call arbitrary code when trying to call functions from IONetworking.kext. This usually results in unpredicted behavior or a kernel panic. In order to recover from such a situation, you should clean the System Caches forcing the linker to recreate it's caches:

1. Delete all the files in /System/Library/Caches and it's subdirectories but leave the directories and the symbolic links intact. This is very important!
2. Reboot.
3. Recreate the kernel cache.
4. Reboot again.

 

The same procedure should be applied when you are experiencing erratic behavior after an update! Please keep in mind that you have to disable SIP temporarily when you are using OC.

 

Troubleshooting

• Make sure you have followed the installation instructions especially when you have issues with certain domains while the others are working fine.
• Use the debug version to collect log data when trying to track down problems. The kernel log messages can be found in /var/log/system.log. For Sierra and above use "log show --predicate "processID == 0" --debug" in order to retrieve kernel logs. Include the log data when asking for support or giving feedback. I'm an engineer, not a clairvoyant.
• Check your BIOS settings. You might want to disable Network Boot and the UEFI Network Stack as these can interfere with the driver.
• Double check that you have removed any other Realtek kext from your system because they could prevent the driver from working properly.
• Verify your bootloader configuration, in particular the kernel flags. Avoid using npci=0x2000 or npci=0x3000. 
• In Terminal run netstat -s in order to display network statistics. Carefully examine the data for any unusual activity like a high number of packets with bad IP header checksums, etc.
• In case auto-configuration of the link layer connection doesn't work it might be necessary to select the medium manually in System Preferences under Network for the interface.
• Use Wireshark to create a packet dump in order to collect diagnostic information.
• Keep in mind that there are many manufacturers of network equipment. Although Ethernet is an IEEE standard different implementations may show different behavior causing incompatibilities. In case you are having trouble try a different switch or a different cable.

 

FAQ

• I want to disable Energy Efficient Ethernet (EEE) but I don't know how?
  • Select a medium without EEE manually.
• WoL from S5 doesn't work with this driver but under Windows it's working. Is this a driver bug?
  • No it isn't, the driver is working as it should because OS X doesn't support WoL from S5.

 

Current status

• The driver has been successfully tested under 10.8.x and 10.9 with the B, C, D, E, F, G and H versions of the RTL8111/8168 and is known to work stable on these devices.

 

Changelog

 

• Version 2.4.2 (2021-04-23)
  • Reworked auto-negotiation to fix issue with 100 MBit/s switches
  • Requires 10.14 or newer.

• Version 2.4.0d4 (2020-10-10)
  • Experimental jumbo frame support up to 9k for chipset 16 and above
  • Requires 10.14 or newer.
• Version 2.3.0 (2020-08-14)
  • Reworked medium section and EEE support to resolve problems with connection establishment and stability.
  • Added option to supply a fallback MAC.
  • Updated Linux sources to 8.047.04 and added support for new family members
  • Requires 10.14 or newer.
• Version 2.2.2 (2018-01-21)
  • Force ASPM state to disabled/enabled according to the config parameter setting.
  • Requires 10.12 or newer.
• Version 2.2.1 (2016-03-12):
  • Updated underlying linux sources from Realtek to 8.041.00.
  • Added support for RTL8111H.
  • Implemented Apple’s polled receive driver model (RXPOLL).
  • Requires 10.11 or newer. Support for older versions of OS X has been dropped.
• Version 2.0.0 (2015-06-21):
  • Uses Apple's private driver interface introduced with 10.8.
  • Supports packet scheduling with QFQ.
  • Please note that 2.0.0 is identical to 2.0.0d2. Only the version number has changed.
• Version 1.2.3 (2014-08-23):
  • Reworked TSO4 and added support for TSO6.
• Version 1.2.2 (2014-08-44):
  • Added an option to disable Active State Power Management (ASPM, default disabled) as ASPM seems to result in unstable operation of some chipsets.
  • Resolved a problem with Link Aggregation after reboot.
  • Added a workaround for the multicast filter bug of chipset 17 (RTL8111F) which prevented Bonjour from working properly
• Version 1.2.0 (2014-04-24):
  • Updated underlying linux sources from Realtek to 8.037.00.
  • Improved interrupt mitigate to use a less aggressive value for 10/100 MBit connections.
• Version 1.1.3 (2013-11-29):
  • Improved transmit queue handling made it possible to reduce CPU load during packet transmission.
  • Improved deadlock detection logic in order to avoid false positives due to lost interrupts.
• Version 1.1.2 (2013-08-03):
  • Improved SMB performance in certain configurations.
  • Faster browsing of large shares.
• Version 1.1.0 (2013-06-08):
  • Support for TCP/IPv6 and UDP/IPv6 checksum offload added (can be disabled in Info.plist).
  • Maximum size of the scatter-gather-list has been increased from 24 to 40 segments to resolve performance issues with TSO4 when offloading large packets which are highly fragmented.
  • TSO4 can be disabled in Info.plist without rebuild.
  • Statistics gathering has been improved to deliver more detailed information (resource shortages, transmitter resets, transmitter interrupt count).
  • The interrupt mitigate settings has been changed to improve performance with SMB and to reduce CPU load.
  • Configuration option added to allow for user defined interrupt mitigate settings without rebuild.
• Version 1.0.4 (2013-05-04):
  • Moved setLinkStatus(kIONetworkLinkValid) from start() to enable(). Cleaned up getDescCommand().
• Version 1.0.3 (2013-04-25):
  • The issue after a reboot from Windows has been eliminated.
• Version 1.0.2 (2013-04-22):
  • Added support for rx checksum offload of TCP and UDP over IPv6.
• Version 1.0.1 (2013-03-31):
  • Improved behavior when rx checksum offload isn't working properly.
  • Adds the chipset's model name to IORegistry so that it will show up in System Profiler.

 

Known Issues

• WoL does not work in certain configurations.
• Old systems with 3 and 4 series chipsets exhibit performance issues in recent versions of macOS because there is no optimized power management for these systems in macOS anymore as Apple dropped support for the underlying hardware a long time ago. In case you are affected, please upgrade your hardware or find an alternative solution because I have no plans for a workaround. Sorry, but I don't think that it's worth the effort.

 

Getting the driver

• The source code can be found here: https://github.com/M...driver_for_OS_X
• There is also a pre-build binary for Mavericks and above: https://www.insanelymac.com/forum/files/file/88-realtekrtl8111-binary/

 

Building from Source

I'm always using the latest version of XCode for development. You can get a free copy of XCode after becoming a member of the Apple developer program. The free membership is sufficient in order to get access to development tools and documentation.

Edited May 6, 2021 by Mieze
Update to version 2.4.2.

[artur_pt]

hello

 

good news...

 

let's see how run the test .

 

thanks

 

good hack

[Maniac10]

I've installed it in my hack (RTL8111E) and it loaded fine and detected the disconnected cable (I'm not using the LAN right now, just wifi). Recently I've been testing Slice's new kext but had some issues with the latest version so I'll try yours a couple of days and report here.

 

kernel[0]: Ethernet [RealtekRTL8111]: EEE support enabled
kernel[0]: Ethernet [RealtekRTL8111]: RTL8168E-VL/8111E-VL: (Chipset 16) at 0xffffff80f08e5000, xx:xx:xx:xx:xx:xx
kernel[0]: RTL8111: Ethernet address xx:xx:xx:xx:xx:xx

[theconnactic]

Works! Thank you very much for this, and congratulations!

 

Is it possible to add support for the 8105E? Could you include it in your driver?

 

All the best!

[Mieze]

Is it possible to add support for the 8105E? Could you include it in your driver?

Unfortunately it isn't because there is no documentation for the Realtek gigabit NICs publicly available so that I had to take the hardware initialization routines from their linux driver and this driver doesn't support the 8105E.

 

Mieze

[theconnactic]

Thanks, Mieze, for the answer!

 

In fact, there is a Linux driver that includes support for the 8105, and Slice even included it in the sources for his driver. I even tried to do something with it, since i'm familiar to C programming, but i lack the necessary knowledge of how to port it to OSX, so i got stuck.

 

All the best!

 

P.S.: the 8105, btw, isn't exactly gigabit ethernet: it's a 10/100 mbs card which usually comes bundled with some cheaper motherboards.

[Mieze]

In fact, there is a Linux driver that includes support for the 8105, and Slice even included it in the sources for his driver. I even tried to do something with it, since i'm familiar to C programming, but i lack the necessary knowledge of how to port it to OSX, so i got stuck.

My driver has a clear cut separation between the OS X code and the linux code. There are only a few interconnections, mainly when the driver calls hardware initialization routines. Assuming that Realtek's linux driver for their Fast Ethernet NICs has a similar architecture it shouldn't be a big deal for you to take my OS X code as a starting point for your development. You would only have to rewrite the hardware dependent parts, like the outputPacket() function and the interrupt handling routines. Maybe you'll also find a leaked datasheet of the 8105E at www.realtek.cz helping you to implement the transmit and receive routines.

 

Mieze

[theconnactic]

Thank you very much for the tips, Mieze! Much appreciated!

 

Best regards!

[Mrengles]

Hey Mieze!

 

Just checking in on the thread with a post so I can receive email updates. :wink2:

 

Keep up the great as always!

 

Mrengles (Robert)

[Vlad]

i would like to take part to this driver development and i think many users want.

As a proposal: could you please put you driver source code on GITHUB or other online versioning portal to be able to track changes between version more easily

[Mieze]

i would like to take part to this driver development and i think many users want.

As a proposal: could you please put you driver source code on GITHUB or other online versioning portal to be able to track changes between version more easily

I already thought about that but at the moment I'm very busy with an iOS project so that there is not much time left for the driver. But this is not a high priority because the project folder contains a git repository that you can use to track changes.

 

Mieze

[willco007]

I already thought about that but at the moment I'm very busy with an iOS project so that there is not much time left for the driver. But this is not a high priority because the project folder contains a git repository that you can use to track changes.

 

I'd also like to get involved, having a central repro would be most helpful. That said, what needs to be done still for the 8111F chipset?

[Mieze]

I'd also like to get involved, having a central repro would be most helpful. That said, what needs to be done still for the 8111F chipset?

As far as I know nothing. Only the 8111B still has a long way to go.

 

Mieze

[willco007]

As far as I know nothing. Only the 8111B still has a long way to go.

OK, I'll pull it down tonight and start using it.

[JUN Ho]

Finally I can use WOL !!

My system have RTL8111E (GA X58A-UD3R motherboard) chip, it works perfectly now.

First time when I try this kext follow your guide in post #1.

It shows connected in system profiler and System Preference, but when I try to use internet it's not connect to internet.

One of my friend informed me to shutdown the system instead of restart after install this kext.

I shutdown system couple minutes after install new kext and boot again, now it works perfectly.

New kext makes my system use WOL. I couldn't use WOL when I use old kext.

Thanks, Mieze !!

[rvxtm]

I own a EP45-extreme (two 8111C) , my question is , if i boot chameleon with kernel patcher plugin (to use /E/E) , does the network work with the driver placed in the Extra/Extensions ? the lynx2mac does not work , only if i place it in the S/L/E folder.

[Mieze]

I own a EP45-extreme (two 8111C) , my question is , if i boot chameleon with kernel patcher plugin (to use /E/E) , does the network work with the driver placed in the Extra/Extensions ? the lynx2mac does not work , only if i place it in the S/L/E folder.

This could be a problem with the kernel cache, because /Extra/Extensions is usually not taken into account when the kernel cache is recreated by Apple provided tools. Better install it in /S/L/E to avoid trouble!

 

Mieze

 

One of my friend informed me to shutdown the system instead of restart after install this kext.

I shutdown system couple minutes after install new kext and boot again, now it works perfectly.

Thanks for posting this. I just added the information to the troubleshooting section.

 

Mieze

[leslieking]

Thank you. Keep up the good work!

[willco007]

Quick follow-up, I loaded it and am up and running. Working great so far; thank you for your work on this!

[Majd Alfhaily]

Would it be possible to add support for RTL8188XX (e.g RTL8188CE)?

[Mieze]

Would it be possible to add support for RTL8188XX (e.g RTL8188CE)?

No, because these are wireless NICs. They are completely different.

 

Mieze

[dmazar]

I've installed your driver to both hacks to see how it goes. Had problem installing it at first: driver was loaded and connected to device, but net was not working, said that cable is not connected. Somehow got resolved by few shutdowns/restarts/reinstalls/deleting and adding ethernet - not sure what helped. But works very nice now.

 

Thank you for your work!

[rvxtm]

This could be a problem with the kernel cache, because /Extra/Extensions is usually not taken into account when the kernel cache is recreated by Apple provided tools. Better install it in /S/L/E to avoid trouble!

 

Mieze

 

 

Thanks for posting this. I just added the information to the troubleshooting section.

 

Mieze

 

On my installer USB, i have the kexts in /extra , with the kernel patcher module.

My problem is that on the first boot, osx uses the audio kext, fakesmc, sata (all inside /extra) only realtek kexts does not load, only after i copy it to s/l/e. My wish was to have the internet on first boot, to configure osx from the initial wizard.

 

I've tried your driver, the download is perfect, but i have around 20kb/s upload if i try to put a file on a server or on my network, something is wrong with the upload.

[Mieze]

On my installer USB, i have the kexts in /extra , with the kernel patcher module.

My problem is that on the first boot, osx uses the audio kext, fakesmc, sata (all inside /extra) only realtek kexts does not load, only after i copy it to s/l/e. My wish was to have the internet on first boot, to configure osx from the initial wizard.

To copy the driver anywhere is not enough. You'll have to repair it's permissions or it will never be used.

I've tried your driver, the download is perfect, but i have around 20kb/s upload if i try to put a file on a server or on my network, something is wrong with the upload.

Please follow the instructions in the troubleshooting section. If the problem persists report back with debug data from /var/log/system.log (all driver related messages), netstat -s output and your OS X version, CPU and mainboard.

 

Mieze

[DOCa Cola]

Thanks for your work. I have replaced the Lnx2 Realtek driver i have been using with yours. I have had rare problems with the Lnx2 driver where out of the blue the whole network was just gone. The transition went smooth (just followed your instructions). Using a 8111F on a P8H77-I. Will see how it performs long term! So far - all looking good.

Thanks!