Skip to content

Commit 0ffa493

Browse files
hangzqcomhangzqcom
committed
Add Debian packaging (DKMS) for Linux kernel drivers
Add .deb package support using DKMS to handle install, uninstall, upgrade, and version control of Qualcomm USB kernel drivers on Debian/Ubuntu systems. New files: - debian/: Full Debian packaging (control, rules, changelog, maintainer scripts) - build-deb.sh: Build script that syncs version from version.h - dkms.conf: DKMS configuration for 4 kernel modules Features: - Builds qtiDevInf, qcom_usb, qcom_usbnet, qcom-serial via DKMS - Auto-rebuilds modules on kernel updates - Blacklists conflicting in-tree modules (qcserial, qmi_wwan, etc.) - Detects and removes conflicting userspace drivers (deb package, /opt/qcom/qcom_userspace, /opt/qcom/QUD, /opt/QTI/QUD, qcom-qud.service) - Cleans up pre-existing manual installs before installation - Installs udev rules for device permissions - Loads modules immediately after installation Updated: - README.md: Added deb package as recommended Linux install method - src/linux/README.md: Added deb package documentation - src/linux/version.h: Version 1.0.6.1 Signed-off-by: Hang Zhang <hangz@qti.qualcomm.com>
1 parent 3e264da commit 0ffa493

18 files changed

Lines changed: 1705 additions & 9 deletions

‎README.md‎

Lines changed: 53 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -13,9 +13,12 @@ The project is organized to facilitate easy compilation, testing, and integratio
1313

1414
```
1515
/
16+
├─ debian/ # Debian packaging files for .deb package build
1617
├─ docs/ # Architecture diagrams and design documents
1718
├─ src/ # Qualcomm USB kernel driver for windows and linux platform
18-
├─ examples/ # samples scripts
19+
├─ examples/ # Sample scripts
20+
├─ build-deb.sh # Build script for generating the .deb package
21+
├─ dkms.conf # DKMS configuration for kernel module management
1922
├─ README.md # This file
2023
└─ ... # Other files and directories
2124
```
@@ -33,6 +36,7 @@ The project is organized to facilitate easy compilation, testing, and integratio
3336

3437
- GNU Make, GCC/Clang.
3538
- Kernel headers for the target kernel version (`linux-headers-$(uname -r)`).
39+
- For deb package build: `debhelper`, `dkms`, `dpkg-dev`, `dh-dkms`.
3640

3741
### Build Steps
3842

@@ -86,9 +90,51 @@ pnputil /add-driver <build_path/driver_name.inf> /install
8690
```bash
8791
pnputil /delete-driver oemxx.inf /uninstall /force
8892
```
89-
#### Linux command:
90-
Navigate to folder `src/linux`
91-
93+
94+
#### Linux — Debian Package (Recommended)
95+
96+
The recommended way to install on Debian/Ubuntu systems is via the `.deb` package, which uses DKMS to automatically build kernel modules for the running kernel and handles install, uninstall, upgrade, and version control.
97+
98+
- Build the package
99+
```bash
100+
# Install build dependencies (one-time)
101+
sudo apt-get install debhelper dkms dpkg-dev dh-dkms
102+
103+
# Build
104+
./build-deb.sh
105+
```
106+
107+
- Installation
108+
```bash
109+
sudo dpkg -i ../qcom-usb-drivers-dkms_<version>_all.deb
110+
```
111+
112+
- Uninstallation
113+
```bash
114+
sudo dpkg -r qcom-usb-drivers-dkms
115+
```
116+
117+
- Check installed version
118+
```bash
119+
dpkg -s qcom-usb-drivers-dkms | grep Version
120+
dkms status
121+
```
122+
123+
- Upgrade
124+
125+
Simply install a newer `.deb` — it automatically removes the old version and installs the new one.
126+
127+
**What the deb package does:**
128+
- Builds all 4 kernel modules (`qtiDevInf`, `qcom_usb`, `qcom_usbnet`, `qcom-serial`) via DKMS
129+
- Automatically rebuilds modules when the kernel is updated
130+
- Installs udev rules and blacklists conflicting in-tree modules
131+
- Handles cleanup of pre-existing manual installs
132+
- Loads modules immediately after installation
133+
134+
#### Linux — Manual Install (Alternative)
135+
136+
Navigate to folder `src/linux`
137+
92138
- Installation
93139
```bash
94140
sudo ./qcom_drivers.sh install
@@ -97,7 +143,8 @@ sudo ./qcom_drivers.sh install
97143
```bash
98144
sudo ./qcom_drivers.sh uninstall
99145
```
100-
For more guidance on build process, FAQ's and troubleshooting, please refer to [README](./src/linux/README.md) document.
146+
147+
For more guidance on build process, FAQ's and troubleshooting, please refer to [README](./src/linux/README.md) document.
101148

102149
## Contributing
103150

@@ -119,4 +166,4 @@ and conditions before contributing.
119166

120167
## Contact
121168

122-
For questions, bug reports, or feature requests, please open an issue on GitHub or contact the maintainers
169+
For questions, bug reports, or feature requests, please open an issue on GitHub or contact the maintainers

‎build-deb.sh‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
#!/bin/bash
2+
# Build script for qcom-usb-drivers-dkms debian package
3+
# Usage: ./build-deb.sh
4+
#
5+
# Prerequisites: sudo apt-get install debhelper dkms dpkg-dev dh-dkms
6+
set -e
7+
8+
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
9+
cd "$SCRIPT_DIR"
10+
11+
PKG_VERSION=$(grep '#define DRIVER_VERSION' src/linux/version.h | awk '{print $3}' | tr -d '"')
12+
echo "Building qcom-usb-drivers-dkms version $PKG_VERSION"
13+
14+
# Update version in dkms.conf if needed
15+
sed -i "s/^PACKAGE_VERSION=.*/PACKAGE_VERSION=\"${PKG_VERSION}\"/" dkms.conf
16+
17+
# Update version in debian/changelog if needed
18+
CHANGELOG_VER=$(head -1 debian/changelog | grep -oP '\(\K[^)]+')
19+
if [ "$CHANGELOG_VER" != "$PKG_VERSION" ]; then
20+
sed -i "1s/([^)]*)/($PKG_VERSION)/" debian/changelog
21+
fi
22+
23+
# Update version in postinst and preinst if needed
24+
sed -i "s/^PKG_VERSION=.*/PKG_VERSION=\"${PKG_VERSION}\"/" debian/qcom-usb-drivers-dkms.postinst
25+
sed -i "s/^PKG_VERSION=.*/PKG_VERSION=\"${PKG_VERSION}\"/" debian/qcom-usb-drivers-dkms.preinst
26+
27+
# Update version in debian/rules if needed
28+
sed -i "s/^PKG_VERSION := .*/PKG_VERSION := ${PKG_VERSION}/" debian/rules
29+
30+
# Check for required build tools
31+
for tool in dpkg-buildpackage debhelper dkms; do
32+
if [ "$tool" = "debhelper" ]; then
33+
dpkg -l debhelper >/dev/null 2>&1 || { echo "Error: $tool not installed. Run: sudo apt-get install $tool"; exit 1; }
34+
elif [ "$tool" = "dkms" ]; then
35+
dpkg -l dkms >/dev/null 2>&1 || { echo "Error: $tool not installed. Run: sudo apt-get install $tool"; exit 1; }
36+
else
37+
command -v $tool >/dev/null 2>&1 || { echo "Error: $tool not found. Run: sudo apt-get install dpkg-dev"; exit 1; }
38+
fi
39+
done
40+
41+
# Check for dh-dkms (provides dh_dkms helper)
42+
dpkg -l dh-dkms >/dev/null 2>&1 || { echo "Error: dh-dkms not installed. Run: sudo apt-get install dh-dkms"; exit 1; }
43+
44+
# Ensure debian/rules is executable
45+
chmod +x debian/rules
46+
47+
# Clean previous build artifacts
48+
rm -f ../qcom-usb-drivers-dkms_*.deb
49+
rm -f ../qcom-usb-drivers-dkms_*.buildinfo
50+
rm -f ../qcom-usb-drivers-dkms_*.changes
51+
rm -rf debian/qcom-usb-drivers-dkms
52+
rm -rf debian/.debhelper
53+
54+
# Build the package (unsigned)
55+
dpkg-buildpackage -us -uc -b
56+
57+
echo ""
58+
echo "========================================"
59+
echo "Build complete! Package files:"
60+
ls -la ../qcom-usb-drivers-dkms_${PKG_VERSION}*.deb 2>/dev/null || echo "(deb file in parent directory)"
61+
echo ""
62+
echo "Install with: sudo dpkg -i ../qcom-usb-drivers-dkms_${PKG_VERSION}_all.deb"
63+
echo "Uninstall with: sudo dpkg -r qcom-usb-drivers-dkms"
64+
echo "Check status: dpkg -s qcom-usb-drivers-dkms"
65+
echo "========================================"

‎debian/.gitignore‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Build artifacts generated by dpkg-buildpackage
2+
.debhelper/
3+
debhelper-build-stamp
4+
files
5+
*.substvars
6+
*.debhelper
7+
qcom-usb-drivers-dkms/

‎debian/60-qcom-usb-drivers.rules‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Qualcomm USB device udev rules
2+
# GobiNet network device
3+
SUBSYSTEM=="net", DRIVERS=="GobiNet", MODE="0660", GROUP="plugdev"
4+
5+
# GobiSerial serial ports
6+
SUBSYSTEM=="tty", DRIVERS=="GobiSerial", MODE="0660", GROUP="dialout"
7+
8+
# QDSS diagnostic devices
9+
SUBSYSTEM=="usb", DRIVERS=="QdssDiag", MODE="0660", GROUP="plugdev"
10+
SUBSYSTEM=="usb", DRIVERS=="QdssMdm", MODE="0660", GROUP="plugdev"

‎debian/changelog‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
qcom-usb-drivers-dkms (1.0.6.1) unstable; urgency=medium
2+
3+
* Initial DKMS debian package for Qualcomm USB kernel drivers
4+
* Includes qtiDevInf, qcom_usb, qcom_usbnet, qcom-serial modules
5+
* Blacklists conflicting in-tree modules (qcserial, qmi_wwan, option, usb_wwan)
6+
* Installs udev rules for Qualcomm USB device permissions
7+
8+
-- Qualcomm Technologies, Inc. <qcom-usb-drivers@qualcomm.com> Tue, 08 Apr 2025 10:00:00 -0700

‎debian/control‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
Source: qcom-usb-drivers-dkms
2+
Section: kernel
3+
Priority: optional
4+
Maintainer: Qualcomm Technologies, Inc. <qcom-usb-drivers@qualcomm.com>
5+
Build-Depends: debhelper-compat (= 13), dkms
6+
Standards-Version: 4.6.0
7+
Rules-Requires-Root: no
8+
9+
Package: qcom-usb-drivers-dkms
10+
Architecture: all
11+
Depends: ${misc:Depends}, dkms, linux-headers-generic | linux-headers-amd64 | linux-headers-arm64
12+
Conflicts: qcom-usb-userspace-drivers, qcom-usb-userspace-drivers-dkms
13+
Replaces: qcom-usb-userspace-drivers, qcom-usb-userspace-drivers-dkms
14+
Description: Qualcomm USB kernel drivers (DKMS)
15+
DKMS package for Qualcomm USB kernel drivers including:
16+
* qtiDevInf - INF file parser for device enumeration
17+
* qcom_usb - USB diagnostic and QDSS driver
18+
* qcom_usbnet - USB network (WWAN) adapter driver
19+
* qcom-serial - USB serial/modem port driver
20+
.
21+
These drivers are automatically built for the running kernel using DKMS
22+
and will be rebuilt when the kernel is updated. Conflicting in-tree
23+
modules (qcserial, qmi_wwan, option, usb_wwan) are blacklisted.

‎debian/copyright‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
2+
Upstream-Name: qcom-usb-drivers
3+
Upstream-Contact: Qualcomm Technologies <qcom-usb-drivers@qualcomm.com>
4+
5+
Files: *
6+
Copyright: 2025-2026 Qualcomm Technologies, Inc. and/or its subsidiaries.
7+
License: BSD-3-Clause
8+
Redistribution and use in source and binary forms, with or without
9+
modification, are permitted provided that the following conditions are met:
10+
.
11+
1. Redistributions of source code must retain the above copyright notice,
12+
this list of conditions and the following disclaimer.
13+
2. Redistributions in binary form must reproduce the above copyright notice,
14+
this list of conditions and the following disclaimer in the documentation
15+
and/or other materials provided with the distribution.
16+
3. Neither the name of the copyright holder nor the names of its contributors
17+
may be used to endorse or promote products derived from this software
18+
without specific prior written permission.
19+
.
20+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21+
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23+
ARE DISCLAIMED.

‎debian/qcom-usb-drivers-dkms.dkms‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
dkms.conf

‎debian/qcom-usb-drivers-dkms.modprobe‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Qualcomm USB kernel drivers - module configuration
2+
# Installed by qcom-usb-drivers-dkms package
3+
4+
# Blacklist conflicting in-tree modules so that Qualcomm drivers are used
5+
blacklist qcserial
6+
install qcserial /bin/false
7+
blacklist qmi_wwan
8+
install qmi_wwan /bin/false
9+
blacklist option
10+
install option /bin/false
11+
blacklist usb_wwan
12+
install usb_wwan /bin/false
13+
14+
# Load Qualcomm USB drivers at boot (qtiDevInf must load first)
15+
softdep qcom_usb pre: qtiDevInf
16+
softdep qcom_usbnet pre: qtiDevInf

‎debian/qcom-usb-drivers-dkms.postinst‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
#!/bin/bash
2+
# Post-installation script for qcom-usb-drivers-dkms
3+
set -e
4+
5+
PKG_NAME="qcom-usb-drivers"
6+
PKG_VERSION="1.0.6.1"
7+
8+
# DEBHELPER runs dkms add/build/install here
9+
#DEBHELPER#
10+
11+
case "$1" in
12+
configure)
13+
# Reload udev rules
14+
udevadm control --reload-rules 2>/dev/null || true
15+
udevadm trigger 2>/dev/null || true
16+
17+
# Update module dependencies
18+
depmod -a 2>/dev/null || true
19+
20+
# Unload conflicting in-tree modules if loaded
21+
for mod in qcserial qmi_wwan cdc_wdm option usb_wwan; do
22+
if lsmod | grep -qw "$mod"; then
23+
echo " Unloading conflicting module: $mod"
24+
rmmod "$mod" 2>/dev/null || true
25+
fi
26+
done
27+
28+
# Load the Qualcomm drivers (order matters: qtiDevInf first)
29+
for mod in qtiDevInf qcom_usb qcom_usbnet qcom-serial; do
30+
modprobe "$mod" 2>/dev/null || true
31+
done
32+
33+
echo "qcom-usb-drivers $PKG_VERSION: modules installed and loaded successfully."
34+
;;
35+
36+
abort-upgrade|abort-remove|abort-deconfigure)
37+
;;
38+
39+
*)
40+
;;
41+
esac
42+
43+
exit 0

0 commit comments

Comments
 (0)