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