[PATCH 0/3] docs: Convert barrier.txt to rST

[PATCH 0/3] docs: Convert barrier.txt to rST

[Peter Maydell]

This patchset converts docs/barrier.txt to rST, putting
it in the appropriate places:
 * the protocol info lives in interop/
 * the "how to use this" info lives in system/
 * TODO remarks live in the .c file :-)

thanks
-- PMM

Peter Maydell (3):
  docs: Move the protocol part of barrier.txt into interop
  ui/input-barrier: Move TODOs from barrier.txt to a comment
  docs: Move user-facing barrier docs into system manual

 docs/barrier.txt         | 370 ----------------------------------
 docs/interop/barrier.rst | 426 +++++++++++++++++++++++++++++++++++++++
 docs/interop/index.rst   |   1 +
 docs/system/barrier.rst  |  44 ++++
 docs/system/index.rst    |   1 +
 ui/input-barrier.c       |   5 +
 6 files changed, 477 insertions(+), 370 deletions(-)
 delete mode 100644 docs/barrier.txt
 create mode 100644 docs/interop/barrier.rst
 create mode 100644 docs/system/barrier.rst

-- 
2.20.1

[PATCH 1/3] docs: Move the protocol part of barrier.txt into interop

[Peter Maydell]

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

[PATCH 2/3] ui/input-barrier: Move TODOs from barrier.txt to a comment

[Peter Maydell]

docs/barrier.txt has a couple of TODO notes about things to be
implemented in this device; move them into a comment in the
source code.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 docs/barrier.txt   | 4 ----
 ui/input-barrier.c | 5 +++++
 2 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/docs/barrier.txt b/docs/barrier.txt
index 376d0b2d709..54cb5fd8efc 100644
--- a/docs/barrier.txt
+++ b/docs/barrier.txt
@@ -45,8 +45,4 @@
 
         (qemu) object_del barrier0
         (qemu) object_add input-barrier,id=barrier0,name=VM-1
-* TO DO
-
-    - Enable SSL
-    - Manage SetOptions/ResetOptions commands
 
diff --git a/ui/input-barrier.c b/ui/input-barrier.c
index 81b8d04ec8d..2d57ca70791 100644
--- a/ui/input-barrier.c
+++ b/ui/input-barrier.c
@@ -3,6 +3,11 @@
  *
  * This work is licensed under the terms of the GNU GPL, version 2 or later.
  * See the COPYING file in the top-level directory.
+ *
+ * TODO:
+ *
+ *  - Enable SSL
+ *  - Manage SetOptions/ResetOptions commands
  */
 
 #include "qemu/osdep.h"
-- 
2.20.1

[PATCH 3/3] docs: Move user-facing barrier docs into system manual

[Peter Maydell]

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

Re: [PATCH 3/3] docs: Move user-facing barrier docs into system manual

[Paolo Bonzini]

On 27/07/21 22:41, Peter Maydell wrote:
> +where VM-1 is the name the display configured int the Barrier server

in 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,

If the Barrier server

> +by removing and re-adding the input-barrier object, for instance
> +with the help of the HMP monitor::
> +
> +    (qemu) object_del barrier0


Paolo

Re: [PATCH 0/3] docs: Convert barrier.txt to rST

[Paolo Bonzini]

On 27/07/21 22:41, Peter Maydell wrote:
> This patchset converts docs/barrier.txt to rST, putting
> it in the appropriate places:
>   * the protocol info lives in interop/
>   * the "how to use this" info lives in system/
>   * TODO remarks live in the .c file :-)
> 
> thanks
> -- PMM
> 
> Peter Maydell (3):
>    docs: Move the protocol part of barrier.txt into interop
>    ui/input-barrier: Move TODOs from barrier.txt to a comment
>    docs: Move user-facing barrier docs into system manual
> 
>   docs/barrier.txt         | 370 ----------------------------------
>   docs/interop/barrier.rst | 426 +++++++++++++++++++++++++++++++++++++++
>   docs/interop/index.rst   |   1 +
>   docs/system/barrier.rst  |  44 ++++
>   docs/system/index.rst    |   1 +
>   ui/input-barrier.c       |   5 +
>   6 files changed, 477 insertions(+), 370 deletions(-)
>   delete mode 100644 docs/barrier.txt
>   create mode 100644 docs/interop/barrier.rst
>   create mode 100644 docs/system/barrier.rst
> 

Apart from the two typos in patch 3,

Reviewed-by: Paolo Bonzini <pbonzini@redhat.com>

Paolo

Re: [PATCH 2/3] ui/input-barrier: Move TODOs from barrier.txt to a comment

[Philippe Mathieu-Daudé]

On 7/27/21 10:41 PM, Peter Maydell wrote:
> docs/barrier.txt has a couple of TODO notes about things to be
> implemented in this device; move them into a comment in the
> source code.
> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
>  docs/barrier.txt   | 4 ----
>  ui/input-barrier.c | 5 +++++
>  2 files changed, 5 insertions(+), 4 deletions(-)

Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>

Re: [PATCH 1/3] docs: Move the protocol part of barrier.txt into interop

[Laurent Vivier]

Le 27/07/2021 à 22:41, Peter Maydell a écrit :
> 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

Reviewed-by: Laurent Vivier <laurent@vivier.eu>

Re: [PATCH 2/3] ui/input-barrier: Move TODOs from barrier.txt to a comment

[Laurent Vivier]

Le 27/07/2021 à 22:41, Peter Maydell a écrit :
> docs/barrier.txt has a couple of TODO notes about things to be
> implemented in this device; move them into a comment in the
> source code.
> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
>  docs/barrier.txt   | 4 ----
>  ui/input-barrier.c | 5 +++++
>  2 files changed, 5 insertions(+), 4 deletions(-)
> 
> diff --git a/docs/barrier.txt b/docs/barrier.txt
> index 376d0b2d709..54cb5fd8efc 100644
> --- a/docs/barrier.txt
> +++ b/docs/barrier.txt
> @@ -45,8 +45,4 @@
>  
>          (qemu) object_del barrier0
>          (qemu) object_add input-barrier,id=barrier0,name=VM-1
> -* TO DO
> -
> -    - Enable SSL
> -    - Manage SetOptions/ResetOptions commands
>  
> diff --git a/ui/input-barrier.c b/ui/input-barrier.c
> index 81b8d04ec8d..2d57ca70791 100644
> --- a/ui/input-barrier.c
> +++ b/ui/input-barrier.c
> @@ -3,6 +3,11 @@
>   *
>   * This work is licensed under the terms of the GNU GPL, version 2 or later.
>   * See the COPYING file in the top-level directory.
> + *
> + * TODO:
> + *
> + *  - Enable SSL
> + *  - Manage SetOptions/ResetOptions commands
>   */
>  
>  #include "qemu/osdep.h"
> 

Reviewed-by: Laurent Vivier <laurent@vivier.eu>

Re: [PATCH 3/3] docs: Move user-facing barrier docs into system manual

[Laurent Vivier]

Le 27/07/2021 à 22:41, Peter Maydell a écrit :
> 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

Reviewed-by: Laurent Vivier <laurent@vivier.eu>