GUIdocs changed

GUIdocs.md

@@ -0,0 +1,134 @@
+---
+layout: wiki
+title: GUIdocs
+permalink: /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
+
+``` {.wiki}
+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
+
+``` {.wiki}
+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|
+
+