Moore Threads mtgpu Driver OS Lock Bypass

(Note: Send bug reports to pcalau12i@foleosoft.com)

This project provides a patch for the Moore Threads mtgpu kernel driver to bypass an artificial OS distribution restriction. The proprietary driver refuses to load on "unsupported Linux distributions" (meaning, anything except for Ubuntu) by returning error -524 (ENOTSUPP), even on perfectly compatible hardware and kernel versions.

mtgpu 0000:01:00.0: Unsupported OS version: #1 SMP Tue Nov 9 20:32:54 CST 2021
mtgpu 0000:01:00.0: mtdev init failed -524
mtgpu: probe of 0000:01:00.0 failed with error -524

The purpose of this project is to patch the official driver to skip over the OS version check.

Pre-built patched drivers are in the Release tab.

Usage and Installation

This repository automates the extraction, patching, and repacking of the official Moore Threads driver package. You do not need to manually hex-edit any files.

1. Clone this repository to your local machine.
2. Navigate to the official Moore Threads developer portal and download the MUSA SDK 4.2.0 package for the MTT S80. Download URL: https://developer.mthreads.com/sdk/download/musa?equipment=MTT%20S80&os=Ubuntu&driverVersion=&version=4.2.0
3. Ensure the downloaded file is named exactly MUSA_SDK_4.2.0.CC2.1.zip.
4. Place the MUSA_SDK_4.2.0.CC2.1.zip file directly into SDK/ root folder of this cloned repository.
5. Open your terminal in the repository folder and type make, then press Enter.

The Makefile will automatically extract the official driver from the SDK file, locate the proprietary binary blob, apply the assembly-level bypass, and repackage everything into a clean, unlocked Debian package.

Once the build process finishes, you can install the unlocked driver on any compatible Linux distribution using standard package management tools. The patched DEB package can be found in the DEB/ folder.

sudo apt install ./DEB/musa_3.1.0-rc4.2.0-Unlocked_amd64.deb

This project has not been tested on SDKs other than 4.2.0. The choice of this SDK is that it currently (as of time of writing) contains the most up-to-date driver for the MTT S80, as well as is the recommended driver for the official PyTorch Docker container, useful if you wish to run AI models on the GPU.

RPM Support

I have added a process to convert the DEB package into an RPM package for Fedora-based distributions. It is tested and confirmed to be functional on the UOS Server operating system, but I have not tested it further beyond this specific operating system. The RPM package is added to the RPM/ folder.

sudo dnf install ./RPM/musa-3.1.0_rc4.2.0_Unlocked-1.x86_64.rpm

Experimental Driver

The -Unlocked driver above only gets the kernel module to load. Its graphics userspace was built for Ubuntu's old Mesa, so on a modern distro (for example Deepin 25, Mesa 24.3) it does not come up correctly out of the box. The -Experimental package fixes that, so the S80 fully accelerates the desktop and apps:

• 64-bit OpenGL and Vulkan — native on the hardware.
• 32-bit Vulkan — Moore Threads do not ship it at all; -Experimental adds it by translating 32-bit Vulkan calls into the working 64-bit Vulkan stack.
• 32-bit OpenGL — Moore Threads ship this incomplete (the 32-bit back-end libraries are missing), so it normally falls back to software; -Experimental gets it onto the hardware using 32-bit zink which translates Vulkan to OpenGL.

32-bit is accelerated by transparently translating it to the 64-bit driver, system-wide — every app, automatically. Build and install it, then reboot:

make experimental
sudo apt install ./DEB/musa_3.1.0-rc4.2.0-Experimental_amd64.deb
sudo reboot

Test it (mesa-utils:i386 gives you a 32-bit OpenGL app to check with):

sudo apt install mesa-utils:i386
glxgears -geometry 512x512     # should render on the MTT S80
mtt-accel status               # 64-bit and 32-bit should both say MTT S80

Note: a 32-bit OpenGL window must use a width that is a multiple of 64 pixels (512, 640, 1280, 1920, ...) or the image shears — that is why the test uses 512x512. Fullscreen and standard game resolutions are fine. Some games also hit Moore Threads' own driver bugs (GPU hangs) that only Moore Threads can fix.

Full design notes are in docs/experimental-driver.md; a container-based alternative (a fully isolated Mesa 23.2) is in container-tool/.

Compute Driver

The driver tends to break on kernels above 6.1. However, with heavy modification of the source files around the proprietary binary blob, it is possible to get at least the non-graphical components of the driver working (such as, for AI workloads) on more recent Linux kernels.

sudo apt install ./DEB/musa-3.1.0_rc4.2.0_Compute-1.x86_64.deb

Hence, I have made a "compute" version of the driver which I have tested to work on kernel 6.8 and 6.17 with Linux Mint. In this version of the driver, I have also stripped out the vast majority of files, and so it has been reduced in file size by about 90%, because almost all the files in the package relate to graphics (such as Vulkan and OpenGL) which are not functional in this version of the driver.

I have tested this version of the driver with llama.cpp and ComfyUI for text-to-image generation, and in both cases it worked flawlessly. Note that, again, if you want graphics, get the "Unlocked" driver, not the "Compute" driver, which does not do graphics.

If you need a graphical display, I recomend using a PC with an iGPU. I have tested this "compute" driver with the KX-7000's official iGPU drivers on Linux Mint, and the MUSA/mtgpu driver does not conflict with the iGPU driver, so you still get hardware acceleration on the iGPU while the discrete MTT S80 GPU is reserved for compute-only workloads.

Note that for kernels 6.11 and above, they removed certain APIs that the proprietary binary blob uses for memory access, and so it is only possible to use the driver by explicitly enabling IOMMU's "passthrough" mode, giving it direct memory access. You can do this by adding something like iommu=pt to the kernel boot parameters / cmdline.

5.2.0-AI Driver (newest SDK)

The -Compute driver above is built from the old 4.2.0 SDK (driver 3.1.0-rc4.2.0). The -AI driver is the same idea — compute-only, no graphics — but built from Moore Threads' newest 5.2.0 server SDK (a much newer MUSA runtime: libmusa.so.5.2.0, firmware for both GPU generations). Like the -Open driver it applies the two closed-core gate bypasses that let a server build bind to the consumer MTT S80, but instead of the 32-bit graphics bridge it strips the entire graphics/display/video userspace and ships only the MUSA compute runtime + firmware + a headless kernel module.

make ai-5.2.0
sudo apt install ./DEB/musa_5.2.0-AI_amd64.deb

The module is configured headless (display=none disable_fbdev=1 compute_only=1), so — exactly like -Compute — pair it with an iGPU for display and keep the S80 for compute-only workloads.

The bulk of the work, again, is the source around the blob: a kernel build-compatibility patch set (in FILES-AI/, ported from the -Compute tree since both fix the same upstream kernel API changes) so the DKMS module compiles across a wide kernel range. It has been verified to build on every kernel available in the Deepin repositories, 5.15 through 6.18, and carries the boundary fixes needed up to 7.0. As with -Compute, kernels 6.11+ need IOMMU passthrough (iommu=pt) for the blob's memory access.

Version 1.1 Update

This update really only is for the "Compute" version of the driver and gives it Kernel 7.0 support. I have tested it on Ubuntu 26.04 with Kernel 7.

Version 1.2 Update

Incorrect guards were causing it to break on older kernels (tested: 6.6) as well specifically 6.18. Those issues have been patched.

Methodology / Reasoning

Patching the driver just requires disassembling the proprietary binary blob and locating the branch instruction associated with "your operating system is invalid, therefore, jump to the function to display an error and shut down the driver." It is a je instruction.

9dc8a:  75 08                jne    9dc94 <mtgpu_driver_data_init+0x204>
9dc8c:  66 41 81 fe 01 02    cmp    $0x201,%r14w
9dc92:  74 5c                je     9dcf0 <mtgpu_driver_data_init+0x260>
9dc94:  41 0f b7 d6          movzwl %r14w,%edx

Once we locate that instruction, we can just replace it with nop instructions.

9dc8c:  66 41 81 fe 01 02    cmp    $0x201,%r14w
9dc92:  90                   nop
9dc93:  90                   nop
9dc94:  41 0f b7 d6          movzwl %r14w,%edx

Converting from DEB to RPM largely just involves adding a lot of symbolic links, as Debian-based operating systems store libraries in different locations than Fedora-based operating systems. I also had to write new postinst and postrm scripts, which are primarily for dkms compiling the drivers.

The "Compute" version of the driver is the most work. Even though the driver is closed-source and mostly just consists of a singular giant proprietary binary blob, there are many files around it which have to compile at installation-time which allow the operating system to talk to the proprietary binary blob.

It was pointed out in this post that only these surrounding files need to be modified to get the compute portion of the drivers working on later Linux kernels. The proprietary binary blob does not need to be modified as the errors only occur during dkms compilation. However, this person did not provide any code for a working project, so I ended up recreating what he claimed to have done myself.

Sadly, it is not possible to get the graphics portion of the driver working on recent Linux kernels like kernel 7.0, because the errors do indeed occur at runtime inside of the proprietary binary blob, but modifying the surrounding files at least allows us to get the driver working for things like AI workloads on very recent Linux kernels.