Added comments to nonobvious code fragments

appvm/qubes_add_pendrive_script.c

@@ -143,6 +143,8 @@ void suicide(struct xs_handle *xs)
 	exit(1);
 }
 
+// we are DVM, AppVM sends us a document to work on
+// /dev/xvdh contains the dvm_header and document data 
 void dvm_transaction_request(char *seq, struct xs_handle *xs)
 {
 	char filename[1024], cmdbuf[1024];
@@ -189,12 +191,16 @@ void dvm_transaction_request(char *seq, struct xs_handle *xs)
 	if (stat_pre.st_mtime == stat_post.st_mtime)
 		suicide(xs);
 	xs_daemon_close(xs);
+	// if the modify timestamp of the document file has changed, write back the
+	// modified content to the requestor AppVM
 	execl("/usr/lib/qubes/qvm-dvm-transfer", "qvm-dvm-transfer", src_vm,
 	      filename, seq, NULL);
 	syslog(LOG_DAEMON | LOG_ERR, "execl qvm-dvm-transfer");
 	suicide(xs);
 }
 
+// we are AppVM, DVM sends us a modified document
+// /dev/xvdh contains the dvm_header and document data 
 void dvm_transaction_return(char *seq_string, struct xs_handle *xs)
 {
 	int seq = strtoul(seq_string, 0, 10);
@@ -213,6 +219,7 @@ void dvm_transaction_return(char *seq_string, struct xs_handle *xs)
 		goto out_err;
 	}
 	drop_to_user();
+	// read the file name for which the open-in-dvm with transaction=="seq" was started
 	snprintf(db_name, sizeof(db_name), DBDIR "/%d", seq);
 	db_fd = open(db_name, O_RDONLY);
 	if (!db_fd) {

appvm/qubes_penctl.c

@@ -39,6 +39,13 @@ void check_name(unsigned char *s)
 		exit(1);
 	}
 }
+/*
+A tool to request action from qfileexchgd by writing to device/qpen xenstore key. 
+new - please attach a vfat-formatted block device at /dev/xvdg; I will either write some files to it and
+	then request sending it to other AppVM, or I will place dvm_header+some file on it and send it to DVM
+send vmname - detach my /dev/xvdg and attach it to vmname at /dev/xvdh
+umount - I am done with my /dev/xvdh, please detach it
+*/
 
 void usage(char *argv0)
 {

appvm/qvm-open-in-dvm.c

@@ -62,7 +62,12 @@ int get_and_set_seq()
 	close(seq_fd);
 	return seq;
 }
-
+/*
+Write the filename we are sending to DVM to DBDIR/transaction_seq
+When DVM sends us a modified document via transaction with transaction_seq,
+we will know that we are supposed to update the document with the
+filename at DBDIR/transaction_seq
+*/ 
 void write_db(char *name, int seq)
 {
 	int db_fd;
@@ -137,6 +142,7 @@ int main(int argc, char **argv)
 		perror("xs_domain_open");
 		exit(1);
 	}
+	// request a new block device at /dev/xvdg from qfileexchgd
 	if (!xs_write(xs, 0, "device/qpen", "new", 3)) {
 		perror("xs_write");
 		exit(1);
@@ -150,8 +156,10 @@ int main(int argc, char **argv)
 	}
 	setuid(getuid());
 	if (argc == 3)
+		// we are AppVM; get new seq
 		seq = get_and_set_seq();
 	else
+		// we are DVM; use the cmdline transaction_seq
 		seq = strtoul(argv[3], 0, 0);
 	file_fd = open(abs_filename, O_RDONLY);
 	if (file_fd < 0) {
@@ -165,6 +173,9 @@ int main(int argc, char **argv)
 	copy_file(xvdg_fd, file_fd);
 	close(file_fd);
 	close(xvdg_fd);
+	// request qfileexchgd to send our /dev/xvdg to its destination
+	// either "disposable", which means "create DVM for me"
+	// or vmname, meaning this is a reply to originator AppVM
 	snprintf(buf, sizeof(buf), "send %s %d", argv[1], seq);
 	if (!xs_write(xs, 0, "device/qpen", buf, strlen(buf))) {
 		perror("xs_write");

dom0/restore/qubes_restore.c

@@ -197,7 +197,10 @@ void start_guid(int domid, int argc, char **argv)
 	execv("/usr/bin/qubes_guid", guid_args);
 	perror("execv");
 }
-
+// modify the savefile. fd = fd to the open savefile,
+// buf - already read 1st page of the savefile
+// pattern - pattern to search for
+// val - string to replace pattern with
 void fix_savefile(int fd, char *buf, char *pattern, char *val)
 {
 	int i, len = strlen(val), origlen;
@@ -229,6 +232,10 @@ char * dispname_by_dispid(int dispid)
 }
 
 #define NAME_PATTERN "/root-cow.img"
+// replaces the unique portions of the savefile with per-dvm values
+// returns the name of VM the savefile was taken for 
+// by looking for /.../vmname/root-cow.img
+// normally, it should be "templatename-dvm"
 char *fix_savefile_and_get_vmname(int fd, int dispid)
 {
 	static char buf[4096];
@@ -264,6 +271,7 @@ char *fix_savefile_and_get_vmname(int fd, int dispid)
 	return slash + 1;
 }
 
+// restore the cow files as they were just before save
 void unpack_cows(char *name)
 {
 	char vmdir[4096];