diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/barrier.txt | 370 |
1 files changed, 370 insertions, 0 deletions
diff --git a/docs/barrier.txt b/docs/barrier.txt new file mode 100644 index 0000000000..b21d15015d --- /dev/null +++ b/docs/barrier.txt @@ -0,0 +1,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 + |