target/mips: Move MUL opcode check from decode_mxu() to decode_legacy()
[qemu/ar7.git] / docs / barrier.txt
blobb21d15015d962b252bd74bb5dc28c2f4b156295b
1                                 QEMU Barrier Client
4 * About
6     Barrier is a KVM (Keyboard-Video-Mouse) software forked from Symless's
7     synergy 1.9 codebase.
9     See https://github.com/debauchee/barrier
11 * QEMU usage
13     Generally, mouse and keyboard are grabbed through the QEMU video
14     interface emulation.
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.
21     The QEMU Barrier client avoids this by implementing directly the Barrier
22     protocol into QEMU.
24     This protocol is enabled by adding an input-barrier object to QEMU.
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>]
31     The object can be added on the QEMU command line, for instance with:
33         ... -object input-barrier,id=barrier0,name=VM-1 ...
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.
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.
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:
46         (qemu) object_del barrier0
47         (qemu) object_add input-barrier,id=barrier0,name=VM-1
49 * Message format
51     Message format between the server and client is in two parts:
53         1- the payload length is a 32bit integer in network endianness,
54         2- the payload
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.
61 * Protocol Description (from barrier/src/lib/barrier/protocol_types.h)
63     - barrierCmdHello          "Barrier"
65       Direction:  server -> client
66       Parameters: { int16_t minor, int16_t major }
67       Description:
69           Say hello to client
70           minor = protocol major version number supported by server
71           major = protocol minor version number supported by server
73     - barrierCmdHelloBack      "Barrier"
75       Direction:  client ->server
76       Parameters: { int16_t minor, int16_t major, char *name}
77       Description:
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
84     - barrierCmdDInfo          "DINF"
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:
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.
97     - barrierCmdCNoop          "CNOP"
99       Direction:  client -> server
100       Parameters: None
101       Description:
103           No operation
105     - barrierCmdCClose         "CBYE"
107       Direction:  server -> client
108       Parameters: None
109       Description:
111           Close connection
113     - barrierCmdCEnter         "CINN"
115       Direction:  server -> client
116       Parameters: { int16_t x, int16_t y, int32_t seq, int16_t modifier }
117       Description:
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.
129     - barrierCmdCLeave         "COUT"
131       Direction:  server -> client
132       Parameters: None
133       Description:
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.
141     - barrierCmdCClipboard     "CCLP"
143       Direction:  server -> client
144       Parameters: { int8_t id, int32_t seq }
145       Description:
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.
153     - barrierCmdCScreenSaver   "CSEC"
155       Direction:  server -> client
156       Parameters: { int8_t started }
157       Description:
159           Screensaver change.
160           started = Screensaver on primary has started (1) or closed (0)
162     - barrierCmdCResetOptions  "CROP"
164       Direction:  server -> client
165       Parameters: None
166       Description:
168           Reset options. Client should reset all of its options to their
169           defaults.
171     - barrierCmdCInfoAck       "CIAK"
173       Direction:  server -> client
174       Parameters: None
175       Description:
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.
181     - barrierCmdCKeepAlive     "CALV"
183       Direction:  server -> client
184       Parameters: None
185       Description:
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.
195     - barrierCmdDKeyDown       "DKDN"
197       Direction:  server -> client
198       Parameters: { int16_t keyid, int16_t modifier [,int16_t button] }
199       Description:
201           Key pressed.
202           keyid    = X11 key id
203           modified = modified mask
204           button   = X11 Xkb keycode (optional)
206     - barrierCmdDKeyRepeat     "DKRP"
208       Direction:  server -> client
209       Parameters: { int16_t keyid, int16_t modifier, int16_t repeat [,int16_t button] }
210       Description:
212           Key auto-repeat.
213           keyid    = X11 key id
214           modified = modified mask
215           repeat   = number of repeats
216           button   = X11 Xkb keycode (optional)
218     - barrierCmdDKeyUp         "DKUP"
220       Direction:  server -> client
221       Parameters: { int16_t keyid, int16_t modifier [,int16_t button] }
222       Description:
224           Key released.
225           keyid    = X11 key id
226           modified = modified mask
227           button   = X11 Xkb keycode (optional)
229     - barrierCmdDMouseDown     "DMDN"
231       Direction:  server -> client
232       Parameters: { int8_t button }
233       Description:
235           Mouse button pressed.
236           button = button id
238     - barrierCmdDMouseUp       "DMUP"
240       Direction:  server -> client
241       Parameters: { int8_t button }
242       Description:
244           Mouse button release.
245           button = button id
247     - barrierCmdDMouseMove     "DMMV"
249       Direction:  server -> client
250       Parameters: { int16_t x, int16_t y }
251       Description:
253           Absolute mouse moved.
254           x,y = absolute screen coordinates
256     - barrierCmdDMouseRelMove  "DMRM"
258       Direction:  server -> client
259       Parameters: { int16_t x, int16_t y }
260       Description:
262           Relative mouse moved.
263           x,y = r relative screen coordinates
265     - barrierCmdDMouseWheel    "DMWM"
267       Direction:  server -> client
268       Parameters: { int16_t x , int16_t y } or { int16_t y }
269       Description:
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
277     - barrierCmdDClipboard     "DCLP"
279       Direction:  server -> client
280       Parameters: { int8_t id, int32_t seq, int8_t mark, char *data }
281       Description:
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.
289     - barrierCmdDSetOptions    "DSOP"
291       Direction:  server -> client
292       Parameters: { int32 t nb, { int32_t id, int32_t val }[] }
293       Description:
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
300     - barrierCmdDFileTransfer  "DFTR"
302       Direction:  server -> client
303       Parameters: { int8_t mark, char *content }
304       Description:
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
311     - barrierCmdDDragInfo      "DDRG" int16_t char *
313       Direction:  server -> client
314       Parameters: { int16_t nb, char *content }
315       Description:
317           Drag information.
318           nb      = number of dragging objects
319           content = object's directory
321     - barrierCmdQInfo          "QINF"
323       Direction:  server -> client
324       Parameters: None
325       Description:
327           Query screen info
328           Client should reply with a barrierCmdDInfo
330     - barrierCmdEIncompatible  "EICV"
332       Direction:  server -> client
333       Parameters: { int16_t nb, major *minor }
334       Description:
336           Incompatible version.
337           major = major version
338           minor = minor version
340     - barrierCmdEBusy          "EBSY"
342       Direction:  server -> client
343       Parameters: None
344       Description:
346           Name provided when connecting is already in use.
348     - barrierCmdEUnknown       "EUNK"
350       Direction:  server -> client
351       Parameters: None
352       Description:
354           Unknown client. Name provided when connecting is not in primary's
355            screen configuration map.
357     - barrierCmdEBad           "EBAD"
359       Direction:  server -> client
360       Parameters: None
361       Description:
363           Protocol violation. Server should disconnect after sending this
364           message.
366 * TO DO
368     - Enable SSL
369     - Manage SetOptions/ResetOptions commands