qubes-doc/GUIdocs.md

layout	title	permalink
wiki	GUIdocs	/wiki/GUIdocs/

Qubes GUI protocol

AppVM -> dom0 messages

Proper handling of the below messages is security-critical. Observe that beside two messages (CLIPBOARD and MFNDUMP) the rest have fixed size, so there is no need for error-prone parsing.

Each message starts with the following header

struct msghdr {   
        uint32_t type;
        uint32_t window;
};

The header is followed by message-specific data.

Message name	Structure after header	Action
MSG_CLIPBOARD_DATA	amorphic blob (length determined by the "window" field)	Store the received clipboard content (not parsing in any way)
MSG_CREATE	struct msg_create {
uint32_t x;
uint32_t y;
uint32_t width;
uint32_t height;
uint32_t parent;
uint32_t override_redirect;
};	Create a window with given parameters
MSG_DESTROY	None	Destroy a window
MSG_MAP	struct msg_map_info {
uint32_t transient_for;
uint32_t override_redirect;
};	Map a window with given parameters
MSG_UNMAP	None	Unmap a window
MSG_CONFIGURE	struct msg_configure {
uint32_t x;
uint32_t y;
uint32_t width;
uint32_t height;
uint32_t override_redirect;
};	Change window position/size/type
MSG_MFNDUMP	struct shm_cmd {
uint32_t shmid;
uint32_t width;
uint32_t height;
uint32_t bpp;
uint32_t off;
uint32_t num_mfn;
uint32_t domid;
uint32_t mfns[0];
};	Retrieve the array of mfns that constitute the composition buffer of a remote window.
The "num_mfn" 32bit integers follow the shm_cmd structure.
MSG_SHMIMAGE	struct msg_shmimage {
uint32_t x;
uint32_t y;
uint32_t width;
uint32_t height;
};	Repaint the given window fragment
MSG_WMNAME	struct msg_wmname {
char data[128];
} ;	Set the window name; only printable characters are allowed
MSG_DOCK	None	Dock the window in the tray

Dom0 -> AppVM messages

Proper handling of the below messages is NOT security-critical.

Each message starts with the following header

struct msghdr {   
        uint32_t type;
        uint32_t window;
};

The header is followed by message-specific data. KEYPRESS, BUTTON, MOTION messages pass information extracted from dom0 XEvent; see appropriate event documentation.

Message name	Structure after header	Action
MSG_KEYPRESS	struct msg_keypress {
uint32_t type;
uint32_t x;
uint32_t y;
uint32_t state;
uint32_t keycode;
};	Tell qubes driver to generate a keypress
MSG_BUTTON	struct msg_button {
uint32_t type;
uint32_t x;
uint32_t y;
uint32_t state;
uint32_t button;
};	Tell qubes driver to generate mouseclick
MSG_MOTION	struct msg_motion {
uint32_t x;
uint32_t y;
uint32_t state;
uint32_t is_hint;
};	Tell qubes driver to generate motion
MSG_CONFIGURE	struct msg_configure {
uint32_t x;
uint32_t y;
uint32_t width;
uint32_t height;
uint32_t override_redirect;
};	Change window position/size/type
MSG_MAP	struct msg_map_info {
uint32_t transient_for;
uint32_t override_redirect;
};	Map a window with given parameters
MSG_CLOSE	None	send wmDeleteMessage to the window
MSG_CROSSING	Obsolete	Obsolete, unused
MSG_FOCUS	struct msg_focus {
uint32_t type;
uint32_t mode;
uint32_t detail;
};	Raise a window, XSetInputFocus
MSG_CLIPBOARD_REQ	None	Retrieve the local clipboard, pass contents to gui-daemon
MSG_CLIPBOARD_DATA	amorphic blob	Insert the received data into local clipboard
MSG_EXECUTE	Obsolete	Obsolete, unused
MSG_KEYMAP_NOTIFY	unsigned char remote_keys[32];	Synchronize the keyboard state (key pressed/depressed) with dom0