* [PATCH 1/3] docs: Move the protocol part of barrier.txt into interop
2021-07-27 20:41 [PATCH 0/3] docs: Convert barrier.txt to rST Peter Maydell
@ 2021-07-27 20:41 ` Peter Maydell
2021-07-29 9:58 ` Laurent Vivier
2021-07-27 20:41 ` [PATCH 2/3] ui/input-barrier: Move TODOs from barrier.txt to a comment Peter Maydell
` (2 subsequent siblings)
3 siblings, 1 reply; 10+ messages in thread
From: Peter Maydell @ 2021-07-27 20:41 UTC (permalink / raw)
To: qemu-devel; +Cc: Gerd Hoffmann, Laurent Vivier
Most of docs/barrier.txt is describing the protocol implemented
by the input-barrier device. Move this into the interop
section of the manual, and rstify it.
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
docs/barrier.txt | 318 -----------------------------
docs/interop/barrier.rst | 426 +++++++++++++++++++++++++++++++++++++++
docs/interop/index.rst | 1 +
3 files changed, 427 insertions(+), 318 deletions(-)
create mode 100644 docs/interop/barrier.rst
diff --git a/docs/barrier.txt b/docs/barrier.txt
index b21d15015d9..376d0b2d709 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 00000000000..055f2c1aef3
--- /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 b1bab81e2ee..f9801a9c202 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
--
2.20.1
^ permalink raw reply related [flat|nested] 10+ messages in thread* [PATCH 3/3] docs: Move user-facing barrier docs into system manual
2021-07-27 20:41 [PATCH 0/3] docs: Convert barrier.txt to rST Peter Maydell
2021-07-27 20:41 ` [PATCH 1/3] docs: Move the protocol part of barrier.txt into interop Peter Maydell
2021-07-27 20:41 ` [PATCH 2/3] ui/input-barrier: Move TODOs from barrier.txt to a comment Peter Maydell
@ 2021-07-27 20:41 ` Peter Maydell
2021-07-28 7:34 ` Paolo Bonzini
2021-07-29 10:00 ` Laurent Vivier
2021-07-28 7:34 ` [PATCH 0/3] docs: Convert barrier.txt to rST Paolo Bonzini
3 siblings, 2 replies; 10+ messages in thread
From: Peter Maydell @ 2021-07-27 20:41 UTC (permalink / raw)
To: qemu-devel; +Cc: Gerd Hoffmann, Laurent Vivier
The remaining text in docs/barrier.txt is user-facing description
of what the device is and how to use it. Move this into the
system manual and rstify it.
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
docs/barrier.txt | 48 -----------------------------------------
docs/system/barrier.rst | 44 +++++++++++++++++++++++++++++++++++++
docs/system/index.rst | 1 +
3 files changed, 45 insertions(+), 48 deletions(-)
delete mode 100644 docs/barrier.txt
create mode 100644 docs/system/barrier.rst
diff --git a/docs/barrier.txt b/docs/barrier.txt
deleted file mode 100644
index 54cb5fd8efc..00000000000
--- a/docs/barrier.txt
+++ /dev/null
@@ -1,48 +0,0 @@
- 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
-
diff --git a/docs/system/barrier.rst b/docs/system/barrier.rst
new file mode 100644
index 00000000000..a15742b5bc9
--- /dev/null
+++ b/docs/system/barrier.rst
@@ -0,0 +1,44 @@
+QEMU Barrier Client
+===================
+
+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.
+
+`Barrier <https://github.com/debauchee/barrier>`__
+is a KVM (Keyboard-Video-Mouse) software forked from Symless's
+synergy 1.9 codebase.
+
+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
diff --git a/docs/system/index.rst b/docs/system/index.rst
index 650409d1566..7b9276c05f0 100644
--- a/docs/system/index.rst
+++ b/docs/system/index.rst
@@ -20,6 +20,7 @@ or Hypervisor.Framework.
linuxboot
generic-loader
guest-loader
+ barrier
vnc-security
tls
secrets
--
2.20.1
^ permalink raw reply related [flat|nested] 10+ messages in thread