Compiling Realtek 8152, 8156 and 8157 ( RTL8152 ) drivers for QNAP NAS

0-compile-r8152-qnap.md

Compiling Realtek RTL 8152, 8156 and 8157 drivers for QNAP NAS

Note

This guide was last updated on 27th June 2024

Many QNAP NAS devices only come with 1Gbe network interfaces. These devices can easily benefit from a simple network upgrade by connecting the ubiquitious 2.5Gbe USB NICs from Realtek. Unfortunately, some of the older QNAP NAS systems do not support the newer r8156 based 2.5Gbe NICs or r8157 based 5Gbe NICs as they run an older 4.x linux kernel and the r8152 source files included with the older linux kernel are based off an older codebase that predates the 8156/8157 series.

With some elbow grease however, we can build support for the 2.5 & 5 Gbe adapters and easily upgrade functionality.

VM & Build Environment Setup

Whilst any Linux build environment may be possible, I have chosen the older Debian 8. We need to download and install the latest Debian 8 i386 instance from Debian: https://www.debian.org/releases/jessie/debian-installer/

Build Essentials

Once our Linux VM is installed, we must also setup the environment for build. Login as "root" user and install the development packages using apt:

apt-get install build-essential libelf-dev bc

Other libraries may be required depending on the kernel/module build options

Compiler / Toolchain

In order to compile the kernel module for a respective QNAP system, we must identify the compiler on which the system was built. This can be done by querying the NAS itself using an SSH terminal:

cat /proc/version

This will show an output like:

Linux version 4.2.8 (root@U16BuildServer176) (gcc version 4.8.2 20131014 (prerelease) (crosstool-NG linaro-1.13.1-4.8-2013.10 - Linaro GCC 2013.10) ) #2 SMP Thu Jun 29 05:42:26 CST 2023

In the case of the TS-431P arm based system, the kernel was built using linaro-1.13.1-4.8-2013.10, so we need the relevant cross compiler. QNAP have not included this compiler in their GPL Open Source repository so we must obtain it from linaro: https://releases.linaro.org/archive/13.10/components/toolchain/binaries/gcc-linaro-aarch64_be-linux-gnu-4.8-2013.10_linux.tar.bz2

Extract the contents to a directory such as the /opt folder.

QNAP provides other platform cross-compilers on their sourceforge repository: https://sourceforge.net/projects/qosgpl/files/QNAP%20NAS%20Tool%20Chains/

Kernel Source

The NAS Kernel source is available on sourceforge: https://sourceforge.net/projects/qosgpl/files/QNAP%20NAS%20GPL%20Source/

In the example of the TS-431P, we will download and extract GPL_QTS-5.0.0-20211101_Kernel.tar.gz

To complete the build environment, we must copy the appropriate config file for kernel compilation.

In the case of the TS-431P:

cp ~/cp GPL_QTS/kernel_cfg/TS-X31X/linux-4.2-arm.config ~/GPL_QTS/src/linux-4.2/.config

Alternatively, one could also extract this config from the running NAS by downloading and extracting the contents under /proc/config.gz

This file can then be copied to the respective linux src folder.

Example:

gunzip config.gz
cp config ~/GPL_QTS/src/linux-4.2/.config

Compile Linux Kernel

With our build environment set up, we must then compile the linux kernel.

We can do so with a simple command (ensuring we reference our extracted folder locations appropriately:

make ARCH=arm CROSS_COMPILE=/opt/gcc-linaro-arm-linux-gnueabihf-4.8-2013.10_linux/bin/arm-linux-gnueabihf- -C ~/GPL_QTS/src/linux-4.2/ scripts prepare modules_prepare

Compile Realtek Driver

From Realtek source

Download and extract the USB Linux drivers from Realtek's website: https://www.realtek.com/en/component/zoo/category/network-interface-controllers-10-100-1000m-gigabit-ethernet-usb-3-0-software

As of (updated) writing, the current version is 2.18.1

If compiling for a 4.x Linux kernel, we must first modify the contents of the r8152.c source file and replace strscpy with strlcpy for driver versions 2.17.1 onwards. This is to allow compilation on older kernel instances as these versions do not support the strscpy function.

If we don't change this function, we will see an error like below:

make: Entering directory '/root/GPL_QTS/src/linux-4.2'

  WARNING: Symbol version dump ./Module.symvers
           is missing; modules will have no dependencies and modversions.

  CC [M]  /root/r8152-2.17.1/r8152.o
/root/r8152-2.17.1/r8152.c: In function ‘rtl8152_get_drvinfo’:
/root/r8152-2.17.1/r8152.c:18623:2: error: implicit declaration of function ‘strscpy’ [-Werror=implicit-function-declaration]
  strscpy(info->driver, MODULENAME, sizeof(info->driver));
  ^
cc1: some warnings being treated as errors
scripts/Makefile.build:270: recipe for target '/root/r8152-2.17.1/r8152.o' failed
make[1]: *** [/root/r8152-2.17.1/r8152.o] Error 1
Makefile:1503: recipe for target '_module_/root/r8152-2.17.1' failed
make: *** [_module_/root/r8152-2.17.1] Error 2
make: Leaving directory '/root/GPL_QTS/src/linux-4.2'

We can quickly replace the functions in the file using sed:

sed -i -e 's/strscpy/strlcpy/g' r8152.c

From GitHub

Alternatively, download forked source from GitHub which contains the necessary fixes and enhancements: https://github.com/RikshaDriver/realtek-r8152-linux

Compilation

Now we can finally compile the Realtek module:

make ARCH=arm CROSS_COMPILE=/opt/gcc-linaro-arm-linux-gnueabihf-4.8-2013.10_linux/bin/arm-linux-gnueabihf- -C ~/GPL_QTS/src/linux-4.2 M=`pwd` modules EXTRA_CFLAGS='-Os'

We should now have the succesfully compiled kernel module r8152.ko

Download optimized compiled driver v2.18.1 from Realtek for QTS 5.x ARMv7 32-bit NAS (Linux Kernel 4.2.8) - based off TS-431P: https://gist.github.com/RikshaDriver/0388ba3f38f89eb975ebb0b915860ec2/raw/98597c6731c95f21b040c6ebabab37a24e58cf21/r8152_v2.18.1_QTS-5.x_linux-4.2_arm7_32.zip

Install Realtek Driver

In order to install the Realtek USB driver on our Linux system, we must overwite the existing r8152.ko module under /lib/modules/4.2.8/

For a quick an dirty test, upload the kernel module to a folder on the NAS, copy to the modules directory and run modprobe to remove and probe the kernel module:

cp r8152.ko /lib/modules/4.2.8/
modprobe -r r8152
modprobe r8152

The Realtek driver should immediately show up as a network interface:

dmesg | grep 8152
[16401.642702] usbcore: deregistering interface driver r8152
[16404.197265] usbcore: registered new interface driver r8152
[16404.851196] r8152 2-4:1.0 eth2: v2.17.1 (2023/06/13)
[16404.856178] r8152 2-4:1.0 eth2: This product is covered by one or more of the following patents:

Tip

If experiencing adapter stability issues, it is possible the NAS may not be providing sufficient power to the adapter. Consider using an externally powered USB 3 Hub or a USB 3 Y cable which is connected to an external USB power source.

Permantenly Using autorun.sh

For a more permanent installation, the same commands can be run at startup using the autorun.sh capability of the NAS.

We must first tick the "Run user defined process during startup" option to allow autorun.sh loading during bootup.

The autorun.sh file must be stored on the flash storage.

QNAP provides a few methods of mounting the flash storage: https://www.qnap.com/en/how-to/faq/article/running-your-own-application-at-startup

In our case, we will do as follows:

/etc/init.d/init_disk.sh mount_flash_config

We can now manually create or upload our autorun.sh file to /tmp/nasconfig_tmp/autorun.sh

Example autorun.sh:

#!/bin/sh

echo "############ autorun.sh script start ############" >> /dev/kmsg

cp /share/CACHEDEV1_DATA/r8152.ko /lib/modules/4.2.8/
cp /share/CACHEDEV1_DATA/50-usb-realtek-net.rules /lib/udev/rules.d/50-usb-realtek-net.rules
modprobe -r r8152
modprobe r8152

sleep 5

udevadm control --reload-rules && udevadm trigger

sleep 10

echo "############  autorun.sh script end  ############" >> /dev/kmsg

Ensure autorun.sh is executable:

chmod +x /tmp/nasconfig_tmp/autorun.sh

Once completed, unmount the flash drive:

cd ~/
/etc/init.d/init_disk.sh umount_flash_config

Reboot and enjoy 2.5Gb/s speeds!

Using QPKG

The Kernel module can also be packaged as a QPKG and run at startup as an application. This is similar to what is done with the Advanced Network Drivers application from QNAP.

Refer to the QDK guide for more details on creating a QPKG: https://cheng-yuan-hong.gitbook.io/qdk-quick-start-guide/

autorun.sh

#!/bin/sh

echo "############ autorun.sh script start ############" >> /dev/kmsg

cp /share/CACHEDEV1_DATA/r8152.ko /lib/modules/4.2.8/
cp /share/CACHEDEV1_DATA/50-usb-realtek-net.rules /lib/udev/rules.d/50-usb-realtek-net.rules
modprobe -r r8152
modprobe r8152

sleep 5

udevadm control --reload-rules && udevadm trigger

sleep 10


echo "############  autorun.sh script end  ############" >> /dev/kmsg

r8152_v2.18.1_QTS-5.x_linux-4.2_arm7_32.zip

I don't know, but hopefully it will work for you and pretty much any Intel CPU.
https://github.com/kawan2/realtek-r8152-linux/files/15043045/r8152-x86-linux346-v2.zip

Hi kawan2, sorry for the late response - I had to order a new USB-Realtek-Interface and had to wait till it's finally here. First of all: Thanks for compiling the new driver. Unfortunately, after giving it a try, i've got the same failure:

[/lib/modules/3.4.6] # modprobe r8152
modprobe: can't load module r8152 (r8152.ko): unknown symbol in module, or unknown parameter

and

[/lib/modules/3.4.6] # dmesg | grep 8152
[12705.528538] r8152: Unknown symbol dev_kfree_skb_any_reason (err 0)

Maybe you've got any last idea, otherwise, I'll think I have to accept, that this machine/kernel is to old.

My fingers are crossed! Big THANKS!

Sorry, I don't know what else to do to make it work on Linux 3.4.6. Perhaps someone else knows how to rewrite that skb function to work in Linux 3.4.6

Or a long shot is to complain to Realtek, maybe they didn't QA their r8152 driver on older Linux.

Updated the guide with v2.18.1 release. Used -Os optimization for the compiled binary though the default O2 is likely more efficient from a performance perspective.

Have had the latest drivers running stable on a 2.5G adapter connected via a USB powered hub for a considerable soak period. USB Y cable will likely provide slightly better performance, but the external power source needs to be sufficient (i.e. 1500mA) and not another port on the same NAS.

The latest drivers from Realtek also include support for the ASUS C2500 adapters.

It seems support for older kernels below 4.10 is going to get very patchy moving forward.

Hey all.
TS-431P, facing weird issue.
Installed module with no problems, eth2 interface is shown in ifconfig, but in GUI - nada. Tried hotplug, reboot with plugged, everything. Nada.
I even ran ifconfig eth2 10.0.0.111 netmask 255.255.255.0 and that way was able to reach NAS resources. But that's far from ideal.
Any tips, suggestions where to look, which config files to check and compare perhaps?

Thanks to RikshaDriver and all. New life for old NAS.

Hi, by GUI, do you mean the Network & Virtual Switch app? I encountered this with the recent QTS 5.1.8.
Downgraded to 5.1.7 and all is OK with the 2.5G dongle.

On a different note, i think the first make only needs "modules_prepare". "modules_prepare" then internally issues "prepare", "scripts", etc.

Thanks for your reply.
Yes, the Net/Virtual switch app. Is downgrade safe?
I just recently went 4.5.4->5.0->5.1.8. Vaguely recollect horror show of downgrading from bad update years ago on this unit...Teh horror.

I did not notice any issues with downgrading 5.1.8 -> 5.1.7. But maybe I was lucky? I use it as a simple file server. Don't use any other apps.
There is a big warning and they tell the users about the dangers of downgrading :(

Too late, it's already rebooting after downgrade haha. But I think this needs to be addressed going forward. I've been stuck on obsolete firmwares for long enough. Possibly just some config changes? Or an effort to stop non-qnap adapters altogether?
Will add how it went. My powered usb hub isn't here until tomorrow anyway. With none I only got about 3 hours of solid 2.5g link, then it all hung.

ADD: Boom! It's there. Thank you!

Just a warning. Messing with plugging and unplugging USB adapter finally messed up stuff so hard, that main bond0 interface was gone. I think I'm going to go back to 5.1.8 for now and just ifconfig it at startup...

It seems there may be some configuration problems post 5.1.7 upgrade as the adapter had also disappeared off the Network & Virtual Switch app for me.

I fixed this issue inadvertently by trying to resolve another issue.

A 3 second press of the reset button performs a basic system reset (that is, resets admin password, security, tcp/ip config) without resetting all other config. I had to run this inadvertently to regain access for the admin account but a positive side benefit was the restoration of USB Adapter info and parameters in the Virtual Switch app.

I compiled with two different drivers, the interface appears and looks perfect, but not working . Have QTS 5.2 and VSapp 2.4 installed. Why is QNap making this so complicated? It seems to work on any newer model without any intervention.

I compiled with two different drivers, the interface appears and looks perfect, but not working . Have QTS 5.2 and VSapp 2.4 installed. Why is QNap making this so complicated? It seems to work on any newer model without any intervention.

What is the kernel version for QTS 5.2? Can you paste the output of cat /proc/version?

Had this twice last week in logs (interface deaf/mute until replug):
[1166382.441801] r8152 2-1:1.0 eth2: intr status -EOVERFLOW
[1166382.454129] r8152 2-1:1.0 eth2: Stop submitting intr, status -71
Advice?

A 3 second press of the reset button performs a basic system reset (that is, resets admin password, security, tcp/ip config) without resetting all other config. I had to run this inadvertently to regain access for the admin account but a positive side benefit was the restoration of USB Adapter info and parameters in the Virtual Switch app.

This worked for me on QTS 5.2.0.2860 TS-431P to have the USB ethernet adapter recognized in the Virtual Switch App. However the device reports as a 1GbE connection. Is this normal? transfer speeds at 9000 MTU are in the 112MB/s range.

The 1GBE description does not sound right. After the 3 second reset, the 5.2.0 Virtual Switch shows for me -
Adapter: Adapter 3 (2.5GbE)
NIC model: Realtek RTL8156 2.5GbE Controller
Network Speed: 2.5 Gbps (MTU: 1500)

A side note, I unplugged the power adapter from my USB3 switch and it has been working fine for weeks without error. So a plain unpowered USB3 switch might be sufficient to make the RTL8156 USB dongle stable.