summaryrefslogtreecommitdiff
path: root/docs/barrier.txt
blob: b21d15015d962b252bd74bb5dc28c2f4b156295b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
                                QEMU Barrier Client


* About

    Barrier is a KVM (Keyboard-Video-Mouse) software forked from Symless's
    synergy 1.9 codebase.

    See https://github.com/debauchee/barrier

* QEMU usage

    Generally, mouse and keyboard are grabbed through the QEMU video
    interface emulation.

    But when we want to use a video graphic adapter via a PCI passthrough
    there is no way to provide the keyboard and mouse inputs to the VM
    except by plugging a second set of mouse and keyboard to the host
    or by installing a KVM software in the guest OS.

    The QEMU Barrier client avoids this by implementing directly the Barrier
    protocol into QEMU.

    This protocol is enabled by adding an input-barrier object to QEMU.

    Syntax: input-barrier,id=<object-id>,name=<guest display name>
            [,server=<barrier server address>][,port=<barrier server port>]
            [,x-origin=<x-origin>][,y-origin=<y-origin>]
            [,width=<width>][,height=<height>]

    The object can be added on the QEMU command line, for instance with:

        ... -object input-barrier,id=barrier0,name=VM-1 ...

    where VM-1 is the name the display configured int the Barrier server
    on the host providing the mouse and the keyboard events.

    by default <barrier server address> is "localhost", port is 24800,
    <x-origin> and <y-origin> are set to 0, <width> and <height> to
    1920 and 1080.

    If Barrier server is stopped QEMU needs to be reconnected manually,
    by removing and re-adding the input-barrier object, for instance
    with the help of the HMP monitor:

        (qemu) object_del barrier0
        (qemu) object_add input-barrier,id=barrier0,name=VM-1

* Message format

    Message format between the server and client is in two parts:

        1- the payload length is a 32bit integer in network endianness,
        2- the payload

    The payload starts with a 4byte string (without NUL) which is the
    command. The first command between the server and the client
    is the only command not encoded on 4 bytes ("Barrier").
    The remaining part of the payload is decoded according to the command.

* Protocol Description (from barrier/src/lib/barrier/protocol_types.h)

    - barrierCmdHello          "Barrier"

      Direction:  server -> client
      Parameters: { int16_t minor, int16_t major }
      Description:

          Say hello to client
          minor = protocol major version number supported by server
          major = protocol minor version number supported by server

    - barrierCmdHelloBack      "Barrier"

      Direction:  client ->server
      Parameters: { int16_t minor, int16_t major, char *name}
      Description:

          Respond to hello from server
          minor = protocol major version number supported by client
          major = protocol minor version number supported by client
          name  = client name

    - barrierCmdDInfo          "DINF"

      Direction:  client ->server
      Parameters: { int16_t x_origin, int16_t y_origin, int16_t width, int16_t height, int16_t x, int16_t y}
      Description:

          The client screen must send this message in response to the
          barrierCmdQInfo message.  It must also send this message when the
          screen's resolution changes.  In this case, the client screen should
          ignore any barrierCmdDMouseMove messages until it receives a
          barrierCmdCInfoAck in order to prevent attempts to move the mouse off
          the new screen area.

    - barrierCmdCNoop          "CNOP"

      Direction:  client -> server
      Parameters: None
      Description:

          No operation

    - barrierCmdCClose         "CBYE"

      Direction:  server -> client
      Parameters: None
      Description:

          Close connection

    - barrierCmdCEnter         "CINN"

      Direction:  server -> client
      Parameters: { int16_t x, int16_t y, int32_t seq, int16_t modifier }
      Description:

          Enter screen.
          x,y      = entering screen absolute coordinates
          seq      = sequence number, which is used to order messages between
                     screens.  the secondary screen must return this number
                     with some messages
          modifier = modifier key mask.  this will have bits set for each
                     toggle modifier key that is activated on entry to the
                     screen.  the secondary screen should adjust its toggle
                     modifiers to reflect that state.

    - barrierCmdCLeave         "COUT"

      Direction:  server -> client
      Parameters: None
      Description:

          Leaving screen.  the secondary screen should send clipboard data in
          response to this message for those clipboards that it has grabbed
          (i.e. has sent a barrierCmdCClipboard for and has not received a
          barrierCmdCClipboard for with a greater sequence number) and that
          were grabbed or have changed since the last leave.

    - barrierCmdCClipboard     "CCLP"

      Direction:  server -> client
      Parameters: { int8_t id, int32_t seq }
      Description:

          Grab clipboard. Sent by screen when some other app on that screen
          grabs a clipboard.
          id  = the clipboard identifier
          seq = sequence number. Client must use the sequence number passed in
                the most recent barrierCmdCEnter.  the server always sends 0.

    - barrierCmdCScreenSaver   "CSEC"

      Direction:  server -> client
      Parameters: { int8_t started }
      Description:

          Screensaver change.
          started = Screensaver on primary has started (1) or closed (0)

    - barrierCmdCResetOptions  "CROP"

      Direction:  server -> client
      Parameters: None
      Description:

          Reset options. Client should reset all of its options to their
          defaults.

    - barrierCmdCInfoAck       "CIAK"

      Direction:  server -> client
      Parameters: None
      Description:

          Resolution change acknowledgment. Sent by server in response to a
          client screen's barrierCmdDInfo. This is sent for every
          barrierCmdDInfo, whether or not the server had sent a barrierCmdQInfo.

    - barrierCmdCKeepAlive     "CALV"

      Direction:  server -> client
      Parameters: None
      Description:

          Keep connection alive. Sent by the server periodically to verify
          that connections are still up and running.  clients must reply in
          kind on receipt.  if the server gets an error sending the message or
          does not receive a reply within a reasonable time then the server
          disconnects the client.  if the client doesn't receive these (or any
          message) periodically then it should disconnect from the server.  the
          appropriate interval is defined by an option.

    - barrierCmdDKeyDown       "DKDN"

      Direction:  server -> client
      Parameters: { int16_t keyid, int16_t modifier [,int16_t button] }
      Description:

          Key pressed.
          keyid    = X11 key id
          modified = modified mask
          button   = X11 Xkb keycode (optional)

    - barrierCmdDKeyRepeat     "DKRP"

      Direction:  server -> client
      Parameters: { int16_t keyid, int16_t modifier, int16_t repeat [,int16_t button] }
      Description:

          Key auto-repeat.
          keyid    = X11 key id
          modified = modified mask
          repeat   = number of repeats
          button   = X11 Xkb keycode (optional)

    - barrierCmdDKeyUp         "DKUP"

      Direction:  server -> client
      Parameters: { int16_t keyid, int16_t modifier [,int16_t button] }
      Description:

          Key released.
          keyid    = X11 key id
          modified = modified mask
          button   = X11 Xkb keycode (optional)

    - barrierCmdDMouseDown     "DMDN"

      Direction:  server -> client
      Parameters: { int8_t button }
      Description:

          Mouse button pressed.
          button = button id

    - barrierCmdDMouseUp       "DMUP"

      Direction:  server -> client
      Parameters: { int8_t button }
      Description:

          Mouse button release.
          button = button id

    - barrierCmdDMouseMove     "DMMV"

      Direction:  server -> client
      Parameters: { int16_t x, int16_t y }
      Description:

          Absolute mouse moved.
          x,y = absolute screen coordinates

    - barrierCmdDMouseRelMove  "DMRM"

      Direction:  server -> client
      Parameters: { int16_t x, int16_t y }
      Description:

          Relative mouse moved.
          x,y = r relative screen coordinates

    - barrierCmdDMouseWheel    "DMWM"

      Direction:  server -> client
      Parameters: { int16_t x , int16_t y } or { int16_t y }
      Description:

          Mouse scroll. The delta should be +120 for one tick forward (away
          from the user) or right and -120 for one tick backward (toward the
          user) or left.
          x = x delta
          y = y delta

    - barrierCmdDClipboard     "DCLP"

      Direction:  server -> client
      Parameters: { int8_t id, int32_t seq, int8_t mark, char *data }
      Description:

          Clipboard data.
          id  = clipboard id
          seq = sequence number. The sequence number is 0 when sent by the
                server.  Client screens should use the/ sequence number from
                the most recent barrierCmdCEnter.

    - barrierCmdDSetOptions    "DSOP"

      Direction:  server -> client
      Parameters: { int32 t nb, { int32_t id, int32_t val }[] }
      Description:

          Set options. Client should set the given option/value pairs.
          nb  = numbers of { id, val } entries
          id  = option id
          val = option new value

    - barrierCmdDFileTransfer  "DFTR"

      Direction:  server -> client
      Parameters: { int8_t mark, char *content }
      Description:

          Transfer file data.
          mark = 0 means the content followed is the file size
                 1 means the content followed is the chunk data
                 2 means the file transfer is finished

    - barrierCmdDDragInfo      "DDRG" int16_t char *

      Direction:  server -> client
      Parameters: { int16_t nb, char *content }
      Description:

          Drag information.
          nb      = number of dragging objects
          content = object's directory

    - barrierCmdQInfo          "QINF"

      Direction:  server -> client
      Parameters: None
      Description:

          Query screen info
          Client should reply with a barrierCmdDInfo

    - barrierCmdEIncompatible  "EICV"

      Direction:  server -> client
      Parameters: { int16_t nb, major *minor }
      Description:

          Incompatible version.
          major = major version
          minor = minor version

    - barrierCmdEBusy          "EBSY"

      Direction:  server -> client
      Parameters: None
      Description:

          Name provided when connecting is already in use.

    - barrierCmdEUnknown       "EUNK"

      Direction:  server -> client
      Parameters: None
      Description:

          Unknown client. Name provided when connecting is not in primary's
           screen configuration map.

    - barrierCmdEBad           "EBAD"

      Direction:  server -> client
      Parameters: None
      Description:

          Protocol violation. Server should disconnect after sending this
          message.

* TO DO

    - Enable SSL
    - Manage SetOptions/ResetOptions commands