.TH QCOM-FIRMWARE-EXTRACT 8 "2025-08-24" "qcom-firmware-extract" "System Administration"
.SH NAME
qcom-firmware-extract \- extract Qualcomm Snapdragon X firmware from a local Windows install and package it for Debian/Ubuntu
.SH SYNOPSIS
.B qcom-firmware-extract
.RB [ \-d
.IR PATH ]
.SH DESCRIPTION
.B qcom-firmware-extract
mounts a Windows system partition (BitLocker or plain NTFS), locates Qualcomm DSP firmware files under
.I Windows/System32/DriverStore/FileRepository
and builds a Debian package that installs those files into
.I /lib/firmware/updates/qcom/<device> .
It then installs the package and updates the initramfs so the firmware is available on next boot.

Device selection is automatic: the script reads
.I /proc/device-tree/model
and maps known device models to the appropriate firmware directory.

Unless
.BR \-d
is supplied, the script searches NVMe devices, decrypts a BitLocker volume (read\-only) via
.B dislocker
when needed, or mounts the first plain NTFS partition it finds, also read\-only.

The generated package is named:
.P
.RS
.B qcom-x1e-firmware-extracted-\fI<device>\fR_\fI<YYYYMMDD>\fR_arm64.deb
.RE
.P
and declares \fIBreaks/Replaces/Conflicts\fR against
.B qcom-x1e-firmware-extracted
to avoid file collisions.

Upon successful creation, the script installs the package with
.B apt-get
and runs:
.P
.RS
.B update-initramfs \-kall \-u
.RE
.P
Finally, it prints a message reminding you to reboot.

.SH OPTIONS
.TP
.B \-d \fIPATH
Use an explicit search path instead of mounting a Windows partition.
This should point at the Windows DriverStore FileRepository directory that contains the firmware files, e.g.:
.I /mnt/Windows/System32/DriverStore/FileRepository

.SH SUPPORTED DEVICES
The following models are recognized (by exact or prefix match of
.I /proc/device-tree/model
as shown):

.RS
.TP
Acer Swift 14 AI (SF14-11) \-\- \fIx1e80100/ACER/SF14-11\fR
.TP
ASUS Vivobook S 15 \-\- \fIx1e80100/ASUSTeK/vivobook\-s15\fR
.TP
ASUS Zenbook A14 (UX3407QA[, LCD|, OLED]) \-\- \fIx1p42100/ASUSTeK/zenbook\-a14\fR
.TP
ASUS Zenbook A14 (UX3407RA) \-\- \fIx1e80100/ASUSTeK/zenbook\-a14\fR
.TP
Dell Inspiron 14 Plus 7441 \-\- \fIx1e80100/dell/inspiron\-14\-plus\-7441\fR
.TP
Dell Latitude 7455 \-\- \fIx1e80100/dell/latitude\-7455\fR
.TP
Dell XPS 13 9345 \-\- \fIx1e80100/dell/xps13\-9345\fR
.TP
HP EliteBook 6 G1q* \-\- \fIx1p42100/hp/elitebook\-6\-g1q\fR
.TP
HP EliteBook Ultra G1q \-\- \fIx1e80100/hp/elitebook\-ultra\-g1q\fR
.TP
HP Omnibook X 14 \-\- \fIx1e80100/hp/omnibook\-x14\fR
.TP
Lenovo ThinkPad T14s Gen 6 \-\- \fIx1e80100/LENOVO/21N1\fR
.TP
Lenovo Yoga Slim 7x \-\- \fIx1e80100/LENOVO/83ED\fR
.TP
Microsoft Surface Laptop 7 (13.8 inch | 15 inch) \-\- \fIx1e80100/microsoft/Romulus\fR
.TP
Samsung Galaxy Book4 Edge \-\- \fIx1e80100/SAMSUNG/galaxy\-book4\-edge\fR
.RE

If your device is not listed, the script aborts with an error. Extend the
.I case
statement to add support.

.SH RUNTIME BEHAVIOUR
.IP \(bu 2
Creates a temporary workspace under
.I /tmp/fwfetch.*
and ensures cleanup on exit.
.IP \(bu
Mounts BitLocker volumes read\-only using
.BR dislocker (1)
to a loopback file, then mounts via
.B ntfs-3g
read\-only; plain NTFS partitions are mounted read\-only directly.
.IP \(bu
Copies the newest matching firmware files among:
.RS
adsp_dtbs.elf,
adspr.jsn,
adsps.jsn,
adspua.jsn,
battmgr.jsn,
cdsp_dtbs.elf,
cdspr.jsn,
qcadsp8380.mbn,
qccdsp8380.mbn,
qcdxkmsuc8380.mbn,
qcdxkmsucpurwa.mbn
.RE
.IP \(bu
Installs to
.I /lib/firmware/updates/qcom/<device_path>
with mode 0644.
.IP \(bu
Builds a Debian package using
.B dpkg-deb
and installs it with
.B apt-get
(noninteractive, reinstall, fix dependencies).
.IP \(bu
Runs
.B update-initramfs \-kall \-u
to include firmware in all installed kernels.

.SH REQUIREMENTS
The following tools must be available (typically from Debian/Ubuntu repositories):
.RS
.B dislocker
(for BitLocker volumes),
.B ntfs-3g
(for NTFS),
.B dpkg-deb
,
.B apt-get
,
.B coreutils
,
.B findutils
,
.B mount
,
.B update-initramfs
(from
.BR initramfs-tools ).
.RE
Root privileges are required for mounting, package installation, and updating initramfs.

.SH EXIT STATUS
Returns 0 on success. Non\-zero on error.
Because the script uses
.B set \-e
, unexpected command failures cause immediate exit; on failure it prints the log from its temporary directory.

.SH FILES
.TP
.I /proc/device-tree/model
Used to detect the current device model.
.TP
.I Windows/System32/DriverStore/FileRepository
Default search root on the Windows partition for firmware files.
.TP
.I /lib/firmware/updates/qcom/<device>
Destination for installed firmware files.
.TP
.I /tmp/fwfetch.XXXXXXX/LOG
Build and install log captured during execution.

.SH EXAMPLES
Extract and package firmware by automatically locating and mounting the Windows partition:
.P
.RS
sudo qcom-firmware-extract
.RE
.P
Use a pre\-mounted or copied DriverStore directory:
.P
.RS
sudo qcom-firmware-extract \-d /mnt/Windows/System32/DriverStore/FileRepository
.RE

.SH SECURITY
The script mounts any discovered Windows partition read\-only and decrypts BitLocker volumes via
.B dislocker
in read\-only mode. Verify you are extracting firmware from a trusted Windows installation.

.SH LIMITATIONS
.IP \(bu 2
Only searches NVMe devices (e.g. nvme0n1). Systems using SATA/eMMC are not scanned automatically; use
.BR \-d .
.IP \(bu
Only the listed devices are supported out of the box.
.IP \(bu
Assumes an \fIarm64\fR Debian/Ubuntu target with
.B initramfs-tools
present.

.SH SEE ALSO
.BR dislocker (1),
.BR mount.ntfs (8),
.BR dpkg-deb (1),
.BR update-initramfs (8)

.SH AUTHORS
Script: Tobias Heider and contributors.
Manpage: generated for operational use by administrators.
.SH COPYRIGHT
This script packages firmware extracted from a local Windows installation. Respect the firmware's license terms and your local laws/policies before redistribution.