stubs: Move qemu_timer_notify_cb() and remove qemu_notify_event() stub
[qemu.git] / docs / barrier.txt
1                                 QEMU Barrier Client
2
3
4 * About
5
6     Barrier is a KVM (Keyboard-Video-Mouse) software forked from Symless's
7     synergy 1.9 codebase.
8
9     See https://github.com/debauchee/barrier
10
11 * QEMU usage
12
13     Generally, mouse and keyboard are grabbed through the QEMU video
14     interface emulation.
15
16     But when we want to use a video graphic adapter via a PCI passthrough
17     there is no way to provide the keyboard and mouse inputs to the VM
18     except by plugging a second set of mouse and keyboard to the host
19     or by installing a KVM software in the guest OS.
20
21     The QEMU Barrier client avoids this by implementing directly the Barrier
22     protocol into QEMU.
23
24     This protocol is enabled by adding an input-barrier object to QEMU.
25
26     Syntax: input-barrier,id=<object-id>,name=<guest display name>
27             [,server=<barrier server address>][,port=<barrier server port>]
28             [,x-origin=<x-origin>][,y-origin=<y-origin>]
29             [,width=<width>][,height=<height>]
30
31     The object can be added on the QEMU command line, for instance with:
32
33         ... -object input-barrier,id=barrier0,name=VM-1 ...
34
35     where VM-1 is the name the display configured int the Barrier server
36     on the host providing the mouse and the keyboard events.
37
38     by default <barrier server address> is "localhost", port is 24800,
39     <x-origin> and <y-origin> are set to 0, <width> and <height> to
40     1920 and 1080.
41
42     If Barrier server is stopped QEMU needs to be reconnected manually,
43     by removing and re-adding the input-barrier object, for instance
44     with the help of the HMP monitor:
45
46         (qemu) object_del barrier0
47         (qemu) object_add input-barrier,id=barrier0,name=VM-1
48
49 * Message format
50
51     Message format between the server and client is in two parts:
52
53         1- the payload length is a 32bit integer in network endianness,
54         2- the payload
55
56     The payload starts with a 4byte string (without NUL) which is the
57     command. The first command between the server and the client
58     is the only command not encoded on 4 bytes ("Barrier").
59     The remaining part of the payload is decoded according to the command.
60
61 * Protocol Description (from barrier/src/lib/barrier/protocol_types.h)
62
63     - barrierCmdHello          "Barrier"
64
65       Direction:  server -> client
66       Parameters: { int16_t minor, int16_t major }
67       Description:
68
69           Say hello to client
70           minor = protocol major version number supported by server
71           major = protocol minor version number supported by server
72
73     - barrierCmdHelloBack      "Barrier"
74
75       Direction:  client ->server
76       Parameters: { int16_t minor, int16_t major, char *name}
77       Description:
78
79           Respond to hello from server
80           minor = protocol major version number supported by client
81           major = protocol minor version number supported by client
82           name  = client name
83
84     - barrierCmdDInfo          "DINF"
85
86       Direction:  client ->server
87       Parameters: { int16_t x_origin, int16_t y_origin, int16_t width, int16_t height, int16_t x, int16_t y}
88       Description:
89
90           The client screen must send this message in response to the
91           barrierCmdQInfo message.  It must also send this message when the
92           screen's resolution changes.  In this case, the client screen should
93           ignore any barrierCmdDMouseMove messages until it receives a
94           barrierCmdCInfoAck in order to prevent attempts to move the mouse off
95           the new screen area.
96
97     - barrierCmdCNoop          "CNOP"
98
99       Direction:  client -> server
100       Parameters: None
101       Description:
102
103           No operation
104
105     - barrierCmdCClose         "CBYE"
106
107       Direction:  server -> client
108       Parameters: None
109       Description:
110
111           Close connection
112
113     - barrierCmdCEnter         "CINN"
114
115       Direction:  server -> client
116       Parameters: { int16_t x, int16_t y, int32_t seq, int16_t modifier }
117       Description:
118
119           Enter screen.
120           x,y      = entering screen absolute coordinates
121           seq      = sequence number, which is used to order messages between
122                      screens.  the secondary screen must return this number
123                      with some messages
124           modifier = modifier key mask.  this will have bits set for each
125                      toggle modifier key that is activated on entry to the
126                      screen.  the secondary screen should adjust its toggle
127                      modifiers to reflect that state.
128
129     - barrierCmdCLeave         "COUT"
130
131       Direction:  server -> client
132       Parameters: None
133       Description:
134
135           Leaving screen.  the secondary screen should send clipboard data in
136           response to this message for those clipboards that it has grabbed
137           (i.e. has sent a barrierCmdCClipboard for and has not received a
138           barrierCmdCClipboard for with a greater sequence number) and that
139           were grabbed or have changed since the last leave.
140
141     - barrierCmdCClipboard     "CCLP"
142
143       Direction:  server -> client
144       Parameters: { int8_t id, int32_t seq }
145       Description:
146
147           Grab clipboard. Sent by screen when some other app on that screen
148           grabs a clipboard.
149           id  = the clipboard identifier
150           seq = sequence number. Client must use the sequence number passed in
151                 the most recent barrierCmdCEnter.  the server always sends 0.
152
153     - barrierCmdCScreenSaver   "CSEC"
154
155       Direction:  server -> client
156       Parameters: { int8_t started }
157       Description:
158
159           Screensaver change.
160           started = Screensaver on primary has started (1) or closed (0)
161
162     - barrierCmdCResetOptions  "CROP"
163
164       Direction:  server -> client
165       Parameters: None
166       Description:
167
168           Reset options. Client should reset all of its options to their
169           defaults.
170
171     - barrierCmdCInfoAck       "CIAK"
172
173       Direction:  server -> client
174       Parameters: None
175       Description:
176
177           Resolution change acknowledgment. Sent by server in response to a
178           client screen's barrierCmdDInfo. This is sent for every
179           barrierCmdDInfo, whether or not the server had sent a barrierCmdQInfo.
180
181     - barrierCmdCKeepAlive     "CALV"
182
183       Direction:  server -> client
184       Parameters: None
185       Description:
186
187           Keep connection alive. Sent by the server periodically to verify
188           that connections are still up and running.  clients must reply in
189           kind on receipt.  if the server gets an error sending the message or
190           does not receive a reply within a reasonable time then the server
191           disconnects the client.  if the client doesn't receive these (or any
192           message) periodically then it should disconnect from the server.  the
193           appropriate interval is defined by an option.
194
195     - barrierCmdDKeyDown       "DKDN"
196
197       Direction:  server -> client
198       Parameters: { int16_t keyid, int16_t modifier [,int16_t button] }
199       Description:
200
201           Key pressed.
202           keyid    = X11 key id
203           modified = modified mask
204           button   = X11 Xkb keycode (optional)
205
206     - barrierCmdDKeyRepeat     "DKRP"
207
208       Direction:  server -> client
209       Parameters: { int16_t keyid, int16_t modifier, int16_t repeat [,int16_t button] }
210       Description:
211
212           Key auto-repeat.
213           keyid    = X11 key id
214           modified = modified mask
215           repeat   = number of repeats
216           button   = X11 Xkb keycode (optional)
217
218     - barrierCmdDKeyUp         "DKUP"
219
220       Direction:  server -> client
221       Parameters: { int16_t keyid, int16_t modifier [,int16_t button] }
222       Description:
223
224           Key released.
225           keyid    = X11 key id
226           modified = modified mask
227           button   = X11 Xkb keycode (optional)
228
229     - barrierCmdDMouseDown     "DMDN"
230
231       Direction:  server -> client
232       Parameters: { int8_t button }
233       Description:
234
235           Mouse button pressed.
236           button = button id
237
238     - barrierCmdDMouseUp       "DMUP"
239
240       Direction:  server -> client
241       Parameters: { int8_t button }
242       Description:
243
244           Mouse button release.
245           button = button id
246
247     - barrierCmdDMouseMove     "DMMV"
248
249       Direction:  server -> client
250       Parameters: { int16_t x, int16_t y }
251       Description:
252
253           Absolute mouse moved.
254           x,y = absolute screen coordinates
255
256     - barrierCmdDMouseRelMove  "DMRM"
257
258       Direction:  server -> client
259       Parameters: { int16_t x, int16_t y }
260       Description:
261
262           Relative mouse moved.
263           x,y = r relative screen coordinates
264
265     - barrierCmdDMouseWheel    "DMWM"
266
267       Direction:  server -> client
268       Parameters: { int16_t x , int16_t y } or { int16_t y }
269       Description:
270
271           Mouse scroll. The delta should be +120 for one tick forward (away
272           from the user) or right and -120 for one tick backward (toward the
273           user) or left.
274           x = x delta
275           y = y delta
276
277     - barrierCmdDClipboard     "DCLP"
278
279       Direction:  server -> client
280       Parameters: { int8_t id, int32_t seq, int8_t mark, char *data }
281       Description:
282
283           Clipboard data.
284           id  = clipboard id
285           seq = sequence number. The sequence number is 0 when sent by the
286                 server.  Client screens should use the/ sequence number from
287                 the most recent barrierCmdCEnter.
288
289     - barrierCmdDSetOptions    "DSOP"
290
291       Direction:  server -> client
292       Parameters: { int32 t nb, { int32_t id, int32_t val }[] }
293       Description:
294
295           Set options. Client should set the given option/value pairs.
296           nb  = numbers of { id, val } entries
297           id  = option id
298           val = option new value
299
300     - barrierCmdDFileTransfer  "DFTR"
301
302       Direction:  server -> client
303       Parameters: { int8_t mark, char *content }
304       Description:
305
306           Transfer file data.
307           mark = 0 means the content followed is the file size
308                  1 means the content followed is the chunk data
309                  2 means the file transfer is finished
310
311     - barrierCmdDDragInfo      "DDRG" int16_t char *
312
313       Direction:  server -> client
314       Parameters: { int16_t nb, char *content }
315       Description:
316
317           Drag information.
318           nb      = number of dragging objects
319           content = object's directory
320
321     - barrierCmdQInfo          "QINF"
322
323       Direction:  server -> client
324       Parameters: None
325       Description:
326
327           Query screen info
328           Client should reply with a barrierCmdDInfo
329
330     - barrierCmdEIncompatible  "EICV"
331
332       Direction:  server -> client
333       Parameters: { int16_t nb, major *minor }
334       Description:
335
336           Incompatible version.
337           major = major version
338           minor = minor version
339
340     - barrierCmdEBusy          "EBSY"
341
342       Direction:  server -> client
343       Parameters: None
344       Description:
345
346           Name provided when connecting is already in use.
347
348     - barrierCmdEUnknown       "EUNK"
349
350       Direction:  server -> client
351       Parameters: None
352       Description:
353
354           Unknown client. Name provided when connecting is not in primary's
355            screen configuration map.
356
357     - barrierCmdEBad           "EBAD"
358
359       Direction:  server -> client
360       Parameters: None
361       Description:
362
363           Protocol violation. Server should disconnect after sending this
364           message.
365
366 * TO DO
367
368     - Enable SSL
369     - Manage SetOptions/ResetOptions commands
370