Project Status: Active

This project is actively maintained. Current priorities and planned work are documented below or in GitHub Issues.

readm

Goodix GXFP5130 Linux Fingerprint Driver

English | Türkçe

Full Linux support for the Goodix GXFP5130 fingerprint sensor found in Huawei MateBook laptops — kernel module, userspace tools, libfprint integration, and PAM setup, all in one place.

Works on Huawei MateBook D16 2024 (MCLF-XX). If it works on your machine, please open a compatibility report.

_{Recorded on the maintainer's Huawei MateBook D16 2024: fprintd-enroll (16 stages) and fprintd-verify. The trailing sudo step in the recording was cut off.}

Credits: The original kernel driver, gxfpmoc userspace library, and the libfprint SIGFM fork were created by Void755. This repository packages that work for distribution (Arch package, PAM integration) — see Upstream provenance for exact source snapshots.

---

Upstream status

A first version of the kernel driver was sent to the Linux kernel mailing list as [PATCH 0/4] drivers/misc: add Goodix GXFP5130 eSPI fingerprint sensor driver (July 2026). After review feedback, the series was withdrawn. The current module still contains sensor-specific protocol logic that arguably belongs in userspace, so the design is being reconsidered. There is no timeline for a resubmission.

Until then, the module is out of tree and DKMS is the supported way to install it.

---

What this does

The GXFP5130 is not a USB or PCIe device — it lives on the Embedded Controller's internal SPI bus and is unreachable through any standard Linux driver path. Out of the box, fprintd-enroll prints No devices available and nothing works.

This package fixes that end-to-end:

• Kernel module — eSPI mailbox transport + GPIO handshake; creates /dev/gxfp
• Userspace tools — TLS-PSK provisioning, raw capture, diagnostics
• libfprint fork — GXFP driver + SIGFM matching algorithm
• PAM integration — sudo and the login screen accept a fingerprint

Supported hardware

Laptop	ACPI ID	Firmware	Status
Huawei MateBook D16 2024 (MCLF-XX / M1010)	GXFP5130:00	GF_GCC_EC_20067	✅ Verified
Huawei MateBook MCLG-XX / M1010	GXFP5130:00	GF_GCC_EC_20055	✅ Verified (community report)
Huawei MateBook D (MDG-XX / M1010)	GXFP5130:00	GF_GCC_EC_20055	✅ Verified (community report)
Huawei MateBook 14 2022 (KLVF-XX / M1010)	GXFP5130:00	GF_GCC_EC_20040	⚠️ Partial (community report) — see note below
Other MateBook models withGXFP5130:00	GXFP5130:00	unknown	❓ Untested — please report

On the MateBook 14 2022 (FW GF_GCC_EC_20040), one reporter found verify to be placement-sensitive: centered full-pad presses match, but partial edge/tip captures don't. Enrollment also took more passes than usual (~17). Likely related to the sensor's small capture area; re-enroll using full-pad centered presses if you see this.

Check whether your sensor is present: find /sys/bus/acpi/devices -name 'GXFP5130*'

Prerequisites

Arch Linux:

sudo pacman -S --needed base-devel linux-headers dkms cmake meson ninja \
  mbedtls3 glib2 glib2-devel libgusb pixman nss libgudev cairo opencv doctest fprintd

Use linux-lts-headers if you are running the LTS kernel. Other distributions need the equivalent packages: C/C++ compiler, CMake ≥ 3.16, Meson, Ninja, Mbed TLS, GLib 2, GUsb, pixman, NSS, Cairo, OpenCV ≥ 4.5, fprintd.

Quick start

# 1. Build (no root needed)
./scripts/doctor.sh
./scripts/build.sh

# 2. Install transport + DKMS module
sudo ./scripts/install.sh
sudo modprobe gxfp
./scripts/verify.sh

# 3. Provision the TLS PSK and confirm capture
sudo ./scripts/provision-psk.sh
sudo gxfp_capture --psk-raw32 /var/lib/fprintd/gxfp/psk_raw32.bin

If you dual-boot Windows and the sensor was already provisioned there, extract the existing key instead of replacing it: see userspace/PSK.md.

Install libfprint integration

Installing this fork replaces the stock libfprint package. On Arch, the build script creates a pacman-managed package so removal is tracked:

./scripts/build-arch-package.sh
sudo pacman -U config/arch/libfprint-gxfp-*.pkg.tar.zst
sudo systemctl restart fprintd
fprintd-enroll
fprintd-verify

To return to the distribution package later: sudo pacman -S libfprint.

For other distributions (local install only):

sudo meson install -C build/libfprint
sudo ldconfig
sudo systemctl restart fprintd
fprintd-enroll
fprintd-verify

Debug a session with verbose logging:

sudo systemctl stop fprintd
sudo env FP_GXFP_LOG=1 /usr/lib/fprintd

PAM integration (sudo + login screen)

Add pam_fprintd.so as a sufficient rule above the password line in /etc/pam.d/system-auth:

auth    required    pam_faillock.so   preauth
auth    sufficient  pam_fprintd.so timeout=10   ← add this line
auth    [success=2 default=ignore]  pam_systemd_home.so
auth    [success=1 default=bad]     pam_unix.so  try_first_pass nullok

timeout=10 is important — without it, typing a password causes a ~120 s wait while the fingerprint module times out before falling through to password auth.

The same change in /etc/pam.d/system-login covers the display manager.

Fedora / SELinux (enforcing)

On distributions that ship SELinux enforcing (Fedora), fprintd is denied access to the PSK and to /dev/gxfp, and enrollment fails with read PSK ... failed: Permission denied. setenforce 0 makes it work, so this is a policy problem, not a driver problem. Diagnosed and worked out by @TarekELz in #8, verified by the reporter on Fedora 44 (MateBook 14 2022, FW GF_GCC_EC_20040). Not yet tested by the maintainer.

Two labels are missing:

1. The PSK directory /var/lib/fprintd/gxfp/ is outside Fedora's fprintd rule (/var/lib/fprint, no trailing d), so it stays var_lib_t. restorecon alone changes nothing. Add a rule first:

   sudo semanage fcontext -a -t fprintd_var_lib_t '/var/lib/fprintd(/.*)?'
   sudo restorecon -Rv /var/lib/fprintd

2. /dev/gxfp has no SELinux type and falls back to device_t. A minimal local policy module (from the issue above) defines one. It ships in this repo as config/selinux/gxfp_local.te:

   cd config/selinux
   make -f /usr/share/selinux/devel/Makefile gxfp_local.pp   # needs selinux-policy-devel
   sudo semodule -i gxfp_local.pp
   sudo semanage fcontext -a -t gxfp_device_t '/dev/gxfp'
   sudo restorecon -v /dev/gxfp

Check for remaining denials with sudo ausearch -m avc -ts recent.

Architecture

Browser / sudo / login screen
        │
        ▼
   pam_fprintd.so
        │
        ▼
    fprintd  ←─── libfprint (GXFP driver + SIGFM matcher)
        │
        ▼
   /dev/gxfp  (character device, DKMS kernel module)
        │
        ▼
  eSPI mailbox @ 0xFE800000
  GPIO 816 pulse → EC → GXFP5130 chip (EC-internal SPI)
  GPIO 813 pulse ← EC  (response ready)

The CPU cannot talk to the chip directly. Every command goes through the Embedded Controller via the eSPI mailbox. The kernel module handles the transport; userspace sees a simple read/write character device.

Troubleshooting

Symptom	Likely cause	Fix
NoGXFP5130:00 in /sys/bus/acpi/devices	Fingerprint reader disabled in firmware	Enable in BIOS/UEFI
No/dev/gxfp after modprobe gxfp	Kernel/module version mismatch	Checkmodinfo gxfp vermagic vs uname -r
fprintd-enroll prints No devices available	Module not loaded (no /dev/gxfp), or stock libfprint without the GXFP driver is in use	Check lsmod | grep gxfp and journalctl -k -b -g gxfp; install the patched libfprint-gxfp package built from this repo
Operation not permitted from fprintd	MissingDeviceAllow drop-in	Re-runsudo ./scripts/install.sh, restart fprintd
SSL - Verification of the message MAC failed (TLS MAC verification failure)	Host PSK ≠ sensor PSK	Confirm without fprintd: sudo systemctl stop fprintd && sudo gxfp_capture --psk-raw32 /var/lib/fprintd/gxfp/psk_raw32.bin. If it still fails, extract the key from Windows, or back up /var/lib/fprintd/gxfp and run sudo ./scripts/provision-psk.sh --replace (overwrites the sensor key; Windows' key stops working)
Capture works, enrollment fails	libfprint/SIGFM layer issue	CollectFP_GXFP_LOG=1 output and open an issue
Finger-up occasionally missed	Known firmwareGF_GCC_EC_20067 quirk	Driver retries automatically; no action needed
First enroll attempt fails ~13s in, before any finger prompt: fdt wait-up retry failed: Connection timed out	Observed once on FW GF_GCC_EC_20055; root cause not confirmed	Reboot and retry. If it recurs, in addition to FP_GXFP_LOG=1, capture the kernel-side trace: echo 1 | sudo tee /sys/kernel/debug/gxfp/trace_enable, reproduce, then sudo cat /sys/kernel/debug/gxfp/trace_dump, and attach both to an issue
Verify matches on centered full-pad presses but not on edge/tip captures	Small sensor area, placement-sensitive (observed on FW GF_GCC_EC_20040)	Re-enroll using full-pad centered presses; avoid partial/edge captures
read PSK ... Permission denied or avc: denied for fprintd on Fedora	SELinux enforcing; PSK path and /dev/gxfp unlabeled for fprintd_t	See Fedora / SELinux
On Omarchy, omarchy-setup-security-fingerprint exits with "No fingerprint sensor detected" or replaces libfprint-gxfp	The script detects USB readers only (via sysfs), and this is an eSPI sensor. Reported by choirib on a MateBook D MDG-XX (FW GF_GCC_EC_20055); not tested by the maintainer	Do not run that script. For the lock screen, create /etc/pam.d/omarchy-lock-fingerprint manually
Module missing after kernel upgrade	DKMS rebuild needed	sudo dkms autoinstall -k "$(uname -r)"

Removal

sudo ./scripts/uninstall.sh

Enrolled fingerprints and the PSK are not deleted.

Contributing

See CONTRIBUTING.md.

If the driver works on a MateBook model not listed above, please open a compatibility report — it takes two minutes and helps everyone with the same hardware.

Contributors

• nawka12: modern Arch build fixes (external/DKMS module build, Mbed TLS 3, RX queue allocation) and SIGFM matching fixes (#3), day-to-day SIGFM matching (ratio 0.85 + CLAHE, #11) with its tests (#13), and a print serialization leak fix (#12)
• TarekELz: Fedora/SELinux report and testing (#8), gxfp_local.te policy module (#9)
• fstronin: WAIT_UP fix and wider re-arm budget for firmware GF_GCC_EC_20069 (#14)
• shern2: MateBook MCLG-XX compatibility report and Arch dependency report (#4, #5)
• JonasKenke: MateBook 14 2022 compatibility report (#7)
• choirib: MateBook D MDG-XX compatibility report (#15)

Upstream provenance

• Kernel transport: Void755/gxfp_linux_driver, snapshot 594c372
• Userspace library/tools: Void755/gxfpmoc, snapshot 4b489a7
• libfprint fork: Void755/libfprint, snapshot 1f7941e + OpenCV 5 fallback

Local change to the gxfpmoc snapshot: tools/requirements.txt (a lone cryptography pin that unseal_bb010002.py never imports) was removed, and the matching pip install line in PSK.md.

Data provenance: the 224-byte sensor configuration table (gxfp_milanl_cfg_template, userspace/src/algo/sensor_cfg.c) is byte-identical to the one in Void755/gxfpmoc (commit 2db33f7), which does not document where the bytes came from. The same table appears in other public Goodix driver projects, one of which attributes it to the vendor's Windows driver. We have not verified the original source or its licensing status, and the MIT licence of gxfpmoc may not cover data it did not create.

The stack is experimental and is not affiliated with Goodix or Huawei.

License

Kernel module: GPL-2.0-only libfprint fork: LGPL-2.1+ Userspace tools: GPL-2.0-only