Initial GXFP5130 userspace prototype

README.md

@@ -0,0 +1,99 @@
+# Goodix GXFP5130 userspace prototype
+
+Experimental Linux userspace prototype for the Goodix GXFP5130 fingerprint
+sensor transported through the `/dev/gxfp` EC mailbox ABI.
+
+The low-level initialization, TLS session, finger detection and image capture
+paths work on the tested hardware. The project is **not yet fully integrated
+into libfprint**, and enrollment/verification is not production-ready.
+
+The implementation has been tested on one GXFP5130 device with chip ID
+`0x2504` and the ChicagoHU profile.
+
+## Hardware-validated functionality
+
+- mailbox record I/O through `/dev/gxfp`
+- Goodix request and response framing
+- chip-ID and 64-byte OTP reads
+- OTP CRC validation and DAC calibration extraction
+- OTP-derived 224-byte ChicagoHU configuration generation
+- TLS 1.2 PSK session establishment with the sensor MCU
+- finger-down and finger-up detection
+- repeated image capture in one TLS session
+- 7680-byte packed 12-bit image decoding into 5120 samples
+- CRC-32/MPEG-2 image validation
+- 64x80 12-bit image output and deterministic 8-bit conversion
+- timeout, cancellation and session recovery regression paths
+
+An experimental libfprint image-device skeleton is included under
+`libfprint-driver/`. It can capture images through libfprint, but the final
+enroll/verify pipeline and matching policy remain work in progress.
+
+## Requirements
+
+- Linux with the Goodix EC mailbox transport and `/dev/gxfp`
+- a C11 compiler and GNU Make
+- pkg-config
+- mbedTLS development libraries
+
+The corresponding kernel transport patch is archived at:
+
+<https://lore.kernel.org/platform-driver-x86/20260803074454.49474-1-ertugtopcu0@gmail.com/>
+
+## Build and test
+
+```sh
+make
+sudo ./sensor-probe /dev/gxfp 10
+```
+
+Enable protocol/TLS debug output only when needed:
+
+```sh
+sudo env GXFP_DEBUG=1 ./sensor-probe /dev/gxfp 1
+```
+
+Run cancellation, timeout-recovery and normal-cycle regression tests:
+
+```sh
+sudo ./session-regression /dev/gxfp
+```
+
+## Layout
+
+```text
+include/gxfp/       protocol and session headers
+src/                transport, configuration, TLS, capture and session code
+examples/           hardware probes and session regression program
+tools/              offline capture-analysis utilities
+libfprint-driver/   experimental, incomplete libfprint integration
+docs/               verified protocol documentation
+```
+
+See [docs/protocol.md](docs/protocol.md) for the protocol and capture format.
+
+## Security and compatibility
+
+The TLS material in `src/tls.c` was recovered for interoperability with the
+tested hardware and forms part of this experimental protocol implementation.
+It is not a user password or repository credential. Do not assume that the
+protocol, configuration, TLS material or image geometry applies to another
+Goodix model.
+
+The prototype exposes raw biometric images. Captures, PGM files and enrollment
+templates are ignored by Git and should not be shared without the subject's
+consent.
+
+## Reverse-engineering notes
+
+Protocol and configuration behavior was reconstructed primarily from the
+Windows implementation and verified against live hardware traces. Existing
+community GXFP5130 experiments were used for comparison. The
+`capture-to-pgm` utility is an offline diagnostic tool and is not used by the
+capture/session implementation.
+
+## License
+
+The userspace library, examples and tools are GPL-2.0-only. The experimental
+libfprint integration file carries an LGPL-2.1-or-later SPDX identifier. Full
+license texts are available under `LICENSES/`.