diff options
| -rw-r--r-- | docs/barrier.txt | 318 | ||||
| -rw-r--r-- | docs/interop/barrier.rst | 426 | ||||
| -rw-r--r-- | docs/interop/index.rst | 1 |
3 files changed, 427 insertions, 318 deletions
diff --git a/docs/barrier.txt b/docs/barrier.txt index b21d15015d..376d0b2d70 100644 --- a/docs/barrier.txt +++ b/docs/barrier.txt @@ -45,324 +45,6 @@ (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 diff --git a/docs/interop/barrier.rst b/docs/interop/barrier.rst new file mode 100644 index 0000000000..055f2c1aef --- /dev/null +++ b/docs/interop/barrier.rst @@ -0,0 +1,426 @@ +Barrier client protocol +======================= + +QEMU's ``input-barrier`` device implements the client end of +the KVM (Keyboard-Video-Mouse) software +`Barrier <https://github.com/debauchee/barrier>`__. + +This document briefly describes the protocol as we implement it. + +Message format +-------------- + +Message format between the server and client is in two parts: + +#. the payload length, a 32bit integer in network endianness +#. 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 +-------------------- + +This comes 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" +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +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. + diff --git a/docs/interop/index.rst b/docs/interop/index.rst index b1bab81e2e..f9801a9c20 100644 --- a/docs/interop/index.rst +++ b/docs/interop/index.rst @@ -7,6 +7,7 @@ are useful for making QEMU interoperate with other software. .. toctree:: :maxdepth: 2 + barrier bitmaps dbus dbus-vmstate |