[thirdparty/qemu.git] / docs / barrier.txt

                                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
Commit	Line	Data
6105683d LV	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