qdl: add support for dry run execution

This mode assists in validating the `rawprogram_.xml` and `patch_.xml`
files,  as well as the Firehose commands that are expected to be sent
to the Firehose programmer.

Dry run implementation is also expected to be extended for
the Digests Table generation required for Firehose Validated Image
Programming (VIP).

Example of usage:

$ qdl --dry-run --serial=0AA94EFD --debug prog_firehose_ddr.elf rawprogram*.xml patch*.xml
qdl version v2.1-24-g30ac3a8-dirty
This is a dry-run execution of QDL. No actual flashing has been performed
waiting for programmer...
FIREHOSE WRITE: <?xml version="1.0"?>
<data><configure MemoryName="ufs" MaxPayloadSizeToTargetInBytes="1048576"
verbose="0" ZLPAwareHost="1" SkipStorageInit="0"/></data>

FIREHOSE WRITE: <?xml version="1.0"?>
<data><configure MemoryName="ufs" MaxPayloadSizeToTargetInBytes="0"
verbose="0" ZLPAwareHost="1" SkipStorageInit="0"/></data>

accepted max payload size: 0
FIREHOSE WRITE: <?xml version="1.0"?>
<data><program SECTOR_SIZE_IN_BYTES="4096" num_partition_sectors="131072"
physical_partition_number="0" start_sector="6" filename="efi.bin"/></data>

Signed-off-by: Igor Opaniuk <igor.opaniuk@oss.qualcomm.com>

Author: igoropaniuk

Makefile

@@ -6,10 +6,10 @@ CFLAGS += -O2 -Wall -g `pkg-config --cflags libxml-2.0 libusb-1.0`
 LDFLAGS += `pkg-config --libs libxml-2.0 libusb-1.0`
 prefix := /usr/local
 
-QDL_SRCS := firehose.c qdl.c sahara.c util.c patch.c program.c read.c ufs.c usb.c ux.c
+QDL_SRCS := firehose.c io.c qdl.c sahara.c util.c patch.c program.c read.c sim.c ufs.c usb.c ux.c
 QDL_OBJS := $(QDL_SRCS:.c=.o)
 
-RAMDUMP_SRCS := ramdump.c sahara.c usb.c util.c ux.c
+RAMDUMP_SRCS := ramdump.c sahara.c io.c usb.c sim.c util.c ux.c
 RAMDUMP_OBJS := $(RAMDUMP_SRCS:.c=.o)
 
 KS_OUT := ks

firehose.c

@@ -159,6 +159,11 @@ static int firehose_read(struct qdl_device *qdl, int timeout_ms,
 		}
 		buf[n] = '\0';
 
+		if (qdl->dev_type == QDL_DEVICE_SIM) {
+			ret = 0;
+			break;
+		}
+
 		ux_debug("FIREHOSE READ: %s\n", buf);
 
 		node = firehose_response_parse(buf, n, &error);
@@ -409,6 +414,11 @@ static int firehose_program(struct qdl_device *qdl, struct program *program, int
 		goto out;
 	}
 
+	if (qdl->dev_type == QDL_DEVICE_SIM) {
+		ret = FIREHOSE_ACK;
+		goto out;
+	}
+
 	t0 = time(NULL);
 
 	lseek(fd, (off_t) program->file_offset * program->sector_size, SEEK_SET);

io.c

@@ -0,0 +1,74 @@
+/*
+ * Copyright (c) 2025, Qualcomm Innovation Center, Inc. All rights reserved.
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ * this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ * this list of conditions and the following disclaimer in the documentation
+ * and/or other materials provided with the distribution.
+ *
+ * 3. Neither the name of the copyright holder nor the names of its contributors
+ * may be used to endorse or promote products derived from this software without
+ * specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#include "qdl.h"
+
+struct qdl_device *qdl_init(enum QDL_DEVICE_TYPE type)
+{
+	if (type == QDL_DEVICE_USB)
+		return usb_init();
+
+	if (type == QDL_DEVICE_SIM)
+		return sim_init();
+
+	return NULL;
+}
+
+void qdl_deinit(struct qdl_device *qdl)
+{
+	if (qdl)
+		free(qdl);
+}
+
+void qdl_set_out_chunk_size(struct qdl_device *qdl, long size)
+{
+	qdl->set_out_chunk_size(qdl, size);
+}
+
+int qdl_open(struct qdl_device *qdl, const char *serial)
+{
+	return qdl->open(qdl, serial);
+}
+
+void qdl_close(struct qdl_device *qdl)
+{
+	qdl->close(qdl);
+}
+
+int qdl_read(struct qdl_device *qdl, void *buf, size_t len, unsigned int timeout)
+{
+	return qdl->read(qdl, buf, len, timeout);
+}
+
+int qdl_write(struct qdl_device *qdl, const void *buf, size_t len)
+{
+	return qdl->write(qdl, buf, len);
+}

qdl.c

@@ -55,7 +55,6 @@ enum {
 };
 
 bool qdl_debug;
-static struct qdl_device qdl;
 
 static int detect_type(const char *xml_file)
 {
@@ -103,7 +102,7 @@ static void print_usage(void)
 {
 	extern const char *__progname;
 	fprintf(stderr,
-		"%s [--debug] [--version] [--allow-missing] [--storage <emmc|nand|ufs>] [--finalize-provisioning] [--include <PATH>] [--serial <NUM>] [--out-chunk-size <SIZE>] <prog.mbn> [<program> <patch> ...]\n",
+		"%s [--debug] [--dry-run] [--version] [--allow-missing] [--storage <emmc|nand|ufs>] [--finalize-provisioning] [--include <PATH>] [--serial <NUM>] [--out-chunk-size <SIZE>] <prog.mbn> [<program> <patch> ...]\n",
 		__progname);
 }
 
@@ -121,7 +120,9 @@ int main(int argc, char **argv)
 	int opt;
 	bool qdl_finalize_provisioning = false;
 	bool allow_missing = false;
-	long out_chunk_size;
+	long out_chunk_size = 0;
+	struct qdl_device *qdl = NULL;
+	enum QDL_DEVICE_TYPE qdl_dev_type = QDL_DEVICE_USB;
 
 	static struct option options[] = {
 		{"debug", no_argument, 0, 'd'},
@@ -132,6 +133,7 @@ int main(int argc, char **argv)
 		{"serial", required_argument, 0, 'S'},
 		{"storage", required_argument, 0, 's'},
 		{"allow-missing", no_argument, 0, 'f'},
+		{"dry-run", no_argument, 0, 'n'},
 		{0, 0, 0, 0}
 	};
 
@@ -140,6 +142,9 @@ int main(int argc, char **argv)
 		case 'd':
 			qdl_debug = true;
 			break;
+		case 'n':
+			qdl_dev_type = QDL_DEVICE_SIM;
+			break;
 		case 'v':
 			print_version();
 			return 0;
@@ -154,7 +159,6 @@ int main(int argc, char **argv)
 			break;
 		case OPT_OUT_CHUNK_SIZE:
 			out_chunk_size = strtol(optarg, NULL, 10);
-			qdl_set_out_chunk_size(&qdl, out_chunk_size);
 			break;
 		case 's':
 			storage = optarg;
@@ -174,6 +178,15 @@ int main(int argc, char **argv)
 		return 1;
 	}
 
+	qdl = qdl_init(qdl_dev_type);
+	if (!qdl) {
+		ret = -1;
+		goto out_cleanup;
+	}
+
+	if (out_chunk_size)
+		qdl_set_out_chunk_size(qdl, out_chunk_size);
+
 	ux_init();
 
 	if (qdl_debug)
@@ -213,23 +226,25 @@ int main(int argc, char **argv)
 		}
 	} while (++optind < argc);
 
-	ret = qdl_open(&qdl, serial);
+	ret = qdl_open(qdl, serial);
 	if (ret)
 		goto out_cleanup;
 
-	qdl.mappings[0] = prog_mbn;
-	ret = sahara_run(&qdl, qdl.mappings, true, NULL, NULL);
+	qdl->mappings[0] = prog_mbn;
+	ret = sahara_run(qdl, qdl->mappings, true, NULL, NULL);
 	if (ret < 0)
 		goto out_cleanup;
 
-	ret = firehose_run(&qdl, incdir, storage, allow_missing);
+	ret = firehose_run(qdl, incdir, storage, allow_missing);
 	if (ret < 0)
 		goto out_cleanup;
 
 out_cleanup:
-	qdl_close(&qdl);
+	qdl_close(qdl);
 	free_programs();
 	free_patches();
 
+	qdl_deinit(qdl);
+
 	return !!ret;
 }

qdl.h

@@ -8,30 +8,59 @@
 #include "read.h"
 #include <libxml/tree.h>
 
+#define container_of(ptr, typecast, member) ({                  \
+	void *_ptr = (void *)(ptr);		                \
+	((typecast *)(_ptr - offsetof(typecast, member))); })
+
 #define MAPPING_SZ 64
 
-struct libusb_device_handle;
+enum QDL_DEVICE_TYPE {
+        QDL_DEVICE_USB,
+        QDL_DEVICE_SIM,
+};
 
 struct qdl_device {
-        struct libusb_device_handle *usb_handle;
+        enum QDL_DEVICE_TYPE dev_type;
         int fd;
 
+        int (*open)(struct qdl_device *qdl, const char *serial);
+        int (*read)(struct qdl_device *qdl, void *buf, size_t len, unsigned int timeout);
+        int (*write) (struct qdl_device *qdl, const void *buf, size_t nbytes);
+        void (*close)(struct qdl_device *qdl);
+        void (*set_out_chunk_size)(struct qdl_device *qdl, long size);
+
+        char *mappings[MAPPING_SZ]; // array index is the id from the device
+};
+
+struct libusb_device_handle;
+
+struct qdl_device_usb {
+        struct qdl_device base;
+        struct libusb_device_handle *usb_handle;
+
         int in_ep;
         int out_ep;
 
         size_t in_maxpktsize;
         size_t out_maxpktsize;
         size_t out_chunk_size;
+};
 
-        char *mappings[MAPPING_SZ]; // array index is the id from the device
+struct qdl_device_sim {
+        struct qdl_device base;
 };
 
+struct qdl_device *qdl_init(enum QDL_DEVICE_TYPE type);
+void qdl_deinit(struct qdl_device *qdl);
 int qdl_open(struct qdl_device *qdl, const char *serial);
 void qdl_close(struct qdl_device *qdl);
 int qdl_read(struct qdl_device *qdl, void *buf, size_t len, unsigned int timeout);
 int qdl_write(struct qdl_device *qdl, const void *buf, size_t len);
 void qdl_set_out_chunk_size(struct qdl_device *qdl, long size);
 
+struct qdl_device *usb_init(void);
+struct qdl_device *sim_init(void);
+
 int firehose_run(struct qdl_device *qdl, const char *incdir, const char *storage, bool allow_missing);
 int sahara_run(struct qdl_device *qdl, char *img_arr[], bool single_image,
 	       const char *ramdump_path, const char *ramdump_filter);

ramdump.c

@@ -18,7 +18,9 @@ static void print_usage(void)
 
 int main(int argc, char **argv)
 {
-	struct qdl_device qdl;
+	struct qdl_device_usb qdl;
+	qdl.base.dev_type = QDL_DEVICE_USB;
+
 	char *ramdump_path = ".";
 	char *filter = NULL;
 	char *serial = NULL;
@@ -61,11 +63,11 @@ int main(int argc, char **argv)
 	if (qdl_debug)
 		print_version();
 
-	ret = qdl_open(&qdl, serial);
+	ret = qdl_open(&qdl.base, serial);
 	if (ret)
 		return 1;
 
-	ret = sahara_run(&qdl, NULL, true, ramdump_path, filter);
+	ret = sahara_run(&qdl.base, NULL, true, ramdump_path, filter);
 	if (ret < 0)
 		return 1;
 

sahara.c

@@ -438,6 +438,9 @@ int sahara_run(struct qdl_device *qdl, char *img_arr[], bool single_image,
 	bool done = false;
 	int n;
 
+	if (qdl->dev_type == QDL_DEVICE_SIM)
+		return 0;
+
 	if (ramdump_path) {
 		ramdump_dir = open(ramdump_path, O_DIRECTORY);
 		if (ramdump_dir < 0)

sim.c

@@ -0,0 +1,74 @@
+/*
+ * Copyright (c) 2025, Qualcomm Innovation Center, Inc. All rights reserved.
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ * this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ * this list of conditions and the following disclaimer in the documentation
+ * and/or other materials provided with the distribution.
+ *
+ * 3. Neither the name of the copyright holder nor the names of its contributors
+ * may be used to endorse or promote products derived from this software without
+ * specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ */
+#include "qdl.h"
+
+static int sim_open(struct qdl_device *qdl, const char *serial)
+{
+	ux_info("This is a dry-run execution of QDL. No actual flashing has been performed\n");
+
+	return 0;
+}
+
+static void sim_close(struct qdl_device *qdl)
+{
+	return;
+}
+
+static int sim_read(struct qdl_device *qdl, void *buf, size_t len, unsigned int timeout)
+{
+	return len;
+}
+
+static int sim_write(struct qdl_device *qdl, const void *buf, size_t len)
+{
+	return len;
+}
+
+static void sim_set_out_chunk_size(struct qdl_device *qdl, long size)
+{
+	return;
+}
+
+struct qdl_device *sim_init(void)
+{
+	struct qdl_device *qdl = malloc(sizeof(struct qdl_device_usb));
+	if (!qdl)
+		return NULL;
+
+	qdl->dev_type = QDL_DEVICE_SIM;
+	qdl->open = sim_open;
+	qdl->read = sim_read;
+	qdl->write = sim_write;
+	qdl->close = sim_close;
+	qdl->set_out_chunk_size = sim_set_out_chunk_size;
+
+	return qdl;
+}