xref: /openbmc/qemu/docs/interop/barrier.rst (revision 2e1cacfb)
1Barrier client protocol
2=======================
3
4QEMU's ``input-barrier`` device implements the client end of
5the KVM (Keyboard-Video-Mouse) software
6`Barrier <https://github.com/debauchee/barrier>`__.
7
8This document briefly describes the protocol as we implement it.
9
10Message format
11--------------
12
13Message format between the server and client is in two parts:
14
15#. the payload length, a 32bit integer in network endianness
16#. the payload
17
18The payload starts with a 4byte string (without NUL) which is the
19command. The first command between the server and the client
20is the only command not encoded on 4 bytes ("Barrier").
21The remaining part of the payload is decoded according to the command.
22
23Protocol Description
24--------------------
25
26This comes from ``barrier/src/lib/barrier/protocol_types.h``.
27
28barrierCmdHello  "Barrier"
29^^^^^^^^^^^^^^^^^^^^^^^^^^
30
31Direction:
32  server -> client
33Parameters:
34  ``{ int16_t minor, int16_t major }``
35Description:
36  Say hello to client
37
38  ``minor`` = protocol major version number supported by server
39
40  ``major`` = protocol minor version number supported by server
41
42barrierCmdHelloBack  "Barrier"
43^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
44
45Direction:
46  client ->server
47Parameters:
48  ``{ int16_t minor, int16_t major, char *name}``
49Description:
50  Respond to hello from server
51
52  ``minor`` = protocol major version number supported by client
53
54  ``major`` = protocol minor version number supported by client
55
56  ``name``  = client name
57
58barrierCmdDInfo  "DINF"
59^^^^^^^^^^^^^^^^^^^^^^^
60
61Direction:
62  client ->server
63Parameters:
64  ``{ int16_t x_origin, int16_t y_origin, int16_t width, int16_t height, int16_t x, int16_t y}``
65Description:
66  The client screen must send this message in response to the
67  barrierCmdQInfo message.  It must also send this message when the
68  screen's resolution changes.  In this case, the client screen should
69  ignore any barrierCmdDMouseMove messages until it receives a
70  barrierCmdCInfoAck in order to prevent attempts to move the mouse off
71  the new screen area.
72
73barrierCmdCNoop  "CNOP"
74^^^^^^^^^^^^^^^^^^^^^^^
75
76Direction:
77  client -> server
78Parameters:
79  None
80Description:
81  No operation
82
83barrierCmdCClose "CBYE"
84^^^^^^^^^^^^^^^^^^^^^^^
85
86Direction:
87  server -> client
88Parameters:
89  None
90Description:
91  Close connection
92
93barrierCmdCEnter "CINN"
94^^^^^^^^^^^^^^^^^^^^^^^
95
96Direction:
97  server -> client
98Parameters:
99  ``{ int16_t x, int16_t y, int32_t seq, int16_t modifier }``
100Description:
101  Enter screen.
102
103  ``x``, ``y``  = entering screen absolute coordinates
104
105  ``seq``  = sequence number, which is used to order messages between
106  screens.  the secondary screen must return this number
107  with some messages
108
109  ``modifier`` = modifier key mask.  this will have bits set for each
110  toggle modifier key that is activated on entry to the
111  screen.  the secondary screen should adjust its toggle
112  modifiers to reflect that state.
113
114barrierCmdCLeave "COUT"
115^^^^^^^^^^^^^^^^^^^^^^^
116
117Direction:
118  server -> client
119Parameters:
120  None
121Description:
122  Leaving screen.  the secondary screen should send clipboard data in
123  response to this message for those clipboards that it has grabbed
124  (i.e. has sent a barrierCmdCClipboard for and has not received a
125  barrierCmdCClipboard for with a greater sequence number) and that
126  were grabbed or have changed since the last leave.
127
128barrierCmdCClipboard "CCLP"
129^^^^^^^^^^^^^^^^^^^^^^^^^^^
130
131Direction:
132  server -> client
133Parameters:
134  ``{ int8_t id, int32_t seq }``
135Description:
136  Grab clipboard. Sent by screen when some other app on that screen
137  grabs a clipboard.
138
139  ``id``  = the clipboard identifier
140
141  ``seq`` = sequence number. Client must use the sequence number passed in
142  the most recent barrierCmdCEnter.  the server always sends 0.
143
144barrierCmdCScreenSaver   "CSEC"
145^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
146
147Direction:
148  server -> client
149Parameters:
150  ``{ int8_t started }``
151Description:
152  Screensaver change.
153
154  ``started`` = Screensaver on primary has started (1) or closed (0)
155
156barrierCmdCResetOptions  "CROP"
157^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
158
159Direction:
160  server -> client
161Parameters:
162  None
163Description:
164  Reset options. Client should reset all of its options to their
165  defaults.
166
167barrierCmdCInfoAck   "CIAK"
168^^^^^^^^^^^^^^^^^^^^^^^^^^^
169
170Direction:
171  server -> client
172Parameters:
173  None
174Description:
175  Resolution change acknowledgment. Sent by server in response to a
176  client screen's barrierCmdDInfo. This is sent for every
177  barrierCmdDInfo, whether or not the server had sent a barrierCmdQInfo.
178
179barrierCmdCKeepAlive "CALV"
180^^^^^^^^^^^^^^^^^^^^^^^^^^^
181
182Direction:
183  server -> client
184Parameters:
185  None
186Description:
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
195barrierCmdDKeyDown   "DKDN"
196^^^^^^^^^^^^^^^^^^^^^^^^^^^
197
198Direction:
199  server -> client
200Parameters:
201  ``{ int16_t keyid, int16_t modifier [,int16_t button] }``
202Description:
203  Key pressed.
204
205  ``keyid`` = X11 key id
206
207  ``modified`` = modified mask
208
209  ``button`` = X11 Xkb keycode (optional)
210
211barrierCmdDKeyRepeat "DKRP"
212^^^^^^^^^^^^^^^^^^^^^^^^^^^
213
214Direction:
215  server -> client
216Parameters:
217  ``{ int16_t keyid, int16_t modifier, int16_t repeat [,int16_t button] }``
218Description:
219  Key auto-repeat.
220
221  ``keyid`` = X11 key id
222
223  ``modified`` = modified mask
224
225  ``repeat``   = number of repeats
226
227  ``button``   = X11 Xkb keycode (optional)
228
229barrierCmdDKeyUp "DKUP"
230^^^^^^^^^^^^^^^^^^^^^^^
231
232Direction:
233  server -> client
234Parameters:
235  ``{ int16_t keyid, int16_t modifier [,int16_t button] }``
236Description:
237  Key released.
238
239  ``keyid`` = X11 key id
240
241  ``modified`` = modified mask
242
243  ``button`` = X11 Xkb keycode (optional)
244
245barrierCmdDMouseDown "DMDN"
246^^^^^^^^^^^^^^^^^^^^^^^^^^^
247
248Direction:
249  server -> client
250Parameters:
251  ``{ int8_t button }``
252Description:
253  Mouse button pressed.
254
255  ``button`` = button id
256
257barrierCmdDMouseUp   "DMUP"
258^^^^^^^^^^^^^^^^^^^^^^^^^^^
259
260Direction:
261  server -> client
262Parameters:
263  ``{ int8_t button }``
264Description:
265  Mouse button release.
266
267  ``button`` = button id
268
269barrierCmdDMouseMove "DMMV"
270^^^^^^^^^^^^^^^^^^^^^^^^^^^
271
272Direction:
273  server -> client
274Parameters:
275  ``{ int16_t x, int16_t y }``
276Description:
277  Absolute mouse moved.
278
279  ``x``, ``y`` = absolute screen coordinates
280
281barrierCmdDMouseRelMove  "DMRM"
282^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
283
284Direction:
285  server -> client
286Parameters:
287  ``{ int16_t x, int16_t y }``
288Description:
289  Relative mouse moved.
290
291  ``x``, ``y`` = r relative screen coordinates
292
293barrierCmdDMouseWheel "DMWM"
294^^^^^^^^^^^^^^^^^^^^^^^^^^^^
295
296Direction:
297  server -> client
298Parameters:
299  ``{ int16_t x , int16_t y }`` or ``{ int16_t y }``
300Description:
301  Mouse scroll. The delta should be +120 for one tick forward (away
302  from the user) or right and -120 for one tick backward (toward the
303  user) or left.
304
305  ``x`` = x delta
306
307  ``y`` = y delta
308
309barrierCmdDClipboard "DCLP"
310^^^^^^^^^^^^^^^^^^^^^^^^^^^
311
312Direction:
313  server -> client
314Parameters:
315  ``{ int8_t id, int32_t seq, int8_t mark, char *data }``
316Description:
317  Clipboard data.
318
319  ``id``  = clipboard id
320
321  ``seq`` = sequence number. The sequence number is 0 when sent by the
322  server.  Client screens should use the/ sequence number from
323  the most recent barrierCmdCEnter.
324
325barrierCmdDSetOptions "DSOP"
326^^^^^^^^^^^^^^^^^^^^^^^^^^^^
327
328Direction:
329  server -> client
330Parameters:
331  ``{ int32 t nb, { int32_t id, int32_t val }[] }``
332Description:
333  Set options. Client should set the given option/value pairs.
334
335  ``nb``  = numbers of ``{ id, val }`` entries
336
337  ``id``  = option id
338
339  ``val`` = option new value
340
341barrierCmdDFileTransfer "DFTR"
342^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
343
344Direction:
345  server -> client
346Parameters:
347  ``{ int8_t mark, char *content }``
348Description:
349  Transfer file data.
350
351  * ``mark`` = 0 means the content followed is the file size
352  * 1 means the content followed is the chunk data
353  * 2 means the file transfer is finished
354
355barrierCmdDDragInfo  "DDRG"
356^^^^^^^^^^^^^^^^^^^^^^^^^^^
357
358Direction:
359  server -> client
360Parameters:
361  ``{ int16_t nb, char *content }``
362Description:
363  Drag information.
364
365  ``nb``  = number of dragging objects
366
367  ``content`` = object's directory
368
369barrierCmdQInfo  "QINF"
370^^^^^^^^^^^^^^^^^^^^^^^
371
372Direction:
373  server -> client
374Parameters:
375  None
376Description:
377  Query screen info
378
379  Client should reply with a barrierCmdDInfo
380
381barrierCmdEIncompatible  "EICV"
382^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
383
384Direction:
385  server -> client
386Parameters:
387  ``{ int16_t nb, major *minor }``
388Description:
389  Incompatible version.
390
391  ``major`` = major version
392
393  ``minor`` = minor version
394
395barrierCmdEBusy  "EBSY"
396^^^^^^^^^^^^^^^^^^^^^^^
397
398Direction:
399  server -> client
400Parameters:
401  None
402Description:
403  Name provided when connecting is already in use.
404
405barrierCmdEUnknown   "EUNK"
406^^^^^^^^^^^^^^^^^^^^^^^^^^^
407
408Direction:
409  server -> client
410Parameters:
411  None
412Description:
413  Unknown client. Name provided when connecting is not in primary's
414  screen configuration map.
415
416barrierCmdEBad   "EBAD"
417^^^^^^^^^^^^^^^^^^^^^^^
418
419Direction:
420  server -> client
421Parameters:
422  None
423Description:
424  Protocol violation. Server should disconnect after sending this
425  message.
426
427