From 63d7cb5231deebfb62cca31ac18831d18ebe35e4 Mon Sep 17 00:00:00 2001
From: Marek Marczykowski <marmarek@invisiblethingslab.com>
Date: Thu, 24 May 2012 12:11:03 +0200
Subject: [PATCH] qrexec: describe msg types in header file

---
 qrexec/qrexec.h | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/qrexec/qrexec.h b/qrexec/qrexec.h
index e3a556ea..4313d119 100644
--- a/qrexec/qrexec.h
+++ b/qrexec/qrexec.h
@@ -19,6 +19,8 @@
  *
  */
 
+/* See also http://wiki.qubes-os.org/trac/wiki/Qrexec */
+
 #define QREXEC_DAEMON_SOCKET_DIR "/var/run/qubes"
 #define MAX_FDS 256
 #define MAX_DATA_CHUNK 4096
@@ -30,26 +32,52 @@
 #define MEMINFO_WRITER_PIDFILE "/var/run/meminfo-writer.pid"
 
 enum {
+	/* messages from qrexec_client to qrexec_daemon (both in dom0) */
+	/* start process in VM and pass its stdin/out/err to dom0 */
 	MSG_CLIENT_TO_SERVER_EXEC_CMDLINE = 0x100,
+	/* start process in VM discarding its stdin/out/err (connect to /dev/null) */
 	MSG_CLIENT_TO_SERVER_JUST_EXEC,
+	/* connect to existing process in VM to receive its stdin/out/err 
+	 * struct connect_existing_params passed as data */
 	MSG_CLIENT_TO_SERVER_CONNECT_EXISTING,
 
+	/* messages qrexec_daemon(dom0)->qrexec_agent(VM) */
+	/* same as MSG_CLIENT_TO_SERVER_CONNECT_EXISTING */
 	MSG_SERVER_TO_AGENT_CONNECT_EXISTING,
+	/* same as MSG_CLIENT_TO_SERVER_EXEC_CMDLINE */
 	MSG_SERVER_TO_AGENT_EXEC_CMDLINE,
+	/* same as MSG_CLIENT_TO_SERVER_JUST_EXEC */
 	MSG_SERVER_TO_AGENT_JUST_EXEC,
+	/* pass data to process stdin */
 	MSG_SERVER_TO_AGENT_INPUT,
+	/* detach from process; qrexec_agent should close pipes to process
+	 * stdin/out/err; it's up to the VM child process if it cause its termination */
 	MSG_SERVER_TO_AGENT_CLIENT_END,
 
+	/* flow control, qrexec_daemon->qrexec_agent */
+	/* suspend reading of named fd from child process */
 	MSG_XOFF,
+	/* resume reading of named fd from child process */
 	MSG_XON,
 
+	/* messages qrexec_agent(VM)->qrexec_daemon(dom0) */
+	/* pass data from process stdout */
 	MSG_AGENT_TO_SERVER_STDOUT,
+	/* pass data from process stderr */
 	MSG_AGENT_TO_SERVER_STDERR,
+	/* inform that process terminated and pass its exit code; this should be
+	 * send after all data from stdout/err are send */
 	MSG_AGENT_TO_SERVER_EXIT_CODE,
+	/* call Qubes RPC service
+	 * struct trigger_connect_params passed as data */
 	MSG_AGENT_TO_SERVER_TRIGGER_CONNECT_EXISTING,
 
+	/* messages qrexec_daemon->qrexec_client (both in dom0) */
+	/* same as MSG_AGENT_TO_SERVER_STDOUT */
 	MSG_SERVER_TO_CLIENT_STDOUT,
+	/* same as MSG_AGENT_TO_SERVER_STDERR */
 	MSG_SERVER_TO_CLIENT_STDERR,
+	/* same as MSG_AGENT_TO_SERVER_EXIT_CODE */
 	MSG_SERVER_TO_CLIENT_EXIT_CODE
 };