[common] clipboard: define streamed clipboard ABIs

common/include/common/KVMFR.h

@@ -28,6 +28,7 @@
 #include <stddef.h>
 #include "types.h"
 #include "LGMPConfig.h"
+#include "KVMFRClipboard.h"
 #include "KVMFRInput.h"
 
 #define KVMFR_MAGIC   "KVMFR---"
@@ -63,7 +64,8 @@ enum
   KVMFR_FEATURE_SETCURSORPOS   = 0x1,
   KVMFR_FEATURE_WINDOWSIZE     = 0x2,
   KVMFR_FEATURE_FRAME_SCHEDULE = 0x4,
-  KVMFR_FEATURE_INPUT          = 0x8
+  KVMFR_FEATURE_INPUT          = 0x8,
+  KVMFR_FEATURE_CLIPBOARD      = 0x10
 };
 
 typedef uint32_t KVMFRFeatureFlags;

common/include/common/KVMFRClipboard.h

@@ -0,0 +1,183 @@
+/**
+ * Looking Glass
+ * Copyright © 2017-2026 The Looking Glass Authors
+ * https://looking-glass.io
+ *
+ * This program is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the Free
+ * Software Foundation; either version 2 of the License, or (at your option)
+ * any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+ * more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc., 59
+ * Temple Place, Suite 330, Boston, MA 02111-1307 USA
+ */
+
+#ifndef _H_LG_COMMON_KVMFR_CLIPBOARD_
+#define _H_LG_COMMON_KVMFR_CLIPBOARD_
+
+#pragma once
+
+#include <stddef.h>
+#include <stdint.h>
+
+#define KVMFR_CLIPBOARD_VERSION       1U
+#define KVMFR_CLIPBOARD_SLOT_COUNT    2U
+#define KVMFR_CLIPBOARD_DATA_BYTES    (64U * 1024U)
+#define KVMFR_CLIPBOARD_SIZE_UNKNOWN  UINT64_MAX
+
+enum
+{
+  KVMFR_CLIPBOARD_FORMAT_NONE = 0,
+  KVMFR_CLIPBOARD_FORMAT_TEXT = 1,
+  KVMFR_CLIPBOARD_FORMAT_PNG  = 2,
+  KVMFR_CLIPBOARD_FORMAT_BMP  = 3,
+  KVMFR_CLIPBOARD_FORMAT_TIFF = 4,
+  KVMFR_CLIPBOARD_FORMAT_JPEG = 5
+};
+
+typedef uint32_t KVMFRClipboardFormat;
+
+enum
+{
+  KVMFR_CLIPBOARD_FORMAT_MASK_TEXT = 1U << 0,
+  KVMFR_CLIPBOARD_FORMAT_MASK_PNG  = 1U << 1,
+  KVMFR_CLIPBOARD_FORMAT_MASK_BMP  = 1U << 2,
+  KVMFR_CLIPBOARD_FORMAT_MASK_TIFF = 1U << 3,
+  KVMFR_CLIPBOARD_FORMAT_MASK_JPEG = 1U << 4,
+  KVMFR_CLIPBOARD_FORMAT_MASK_ALL  =
+    KVMFR_CLIPBOARD_FORMAT_MASK_TEXT |
+    KVMFR_CLIPBOARD_FORMAT_MASK_PNG  |
+    KVMFR_CLIPBOARD_FORMAT_MASK_BMP  |
+    KVMFR_CLIPBOARD_FORMAT_MASK_TIFF |
+    KVMFR_CLIPBOARD_FORMAT_MASK_JPEG,
+};
+
+typedef uint32_t KVMFRClipboardFormatFlags;
+
+static inline int kvmfrClipboardFormatValid(KVMFRClipboardFormat format)
+{
+  return format >= KVMFR_CLIPBOARD_FORMAT_TEXT &&
+    format <= KVMFR_CLIPBOARD_FORMAT_JPEG;
+}
+
+static inline KVMFRClipboardFormatFlags kvmfrClipboardFormatFlag(
+  KVMFRClipboardFormat format)
+{
+  return kvmfrClipboardFormatValid(format) ?
+    (KVMFRClipboardFormatFlags)(1U << (format - 1U)) : 0U;
+}
+
+enum
+{
+  KVMFR_CLIPBOARD_MESSAGE_CLAIM       = 1,
+  KVMFR_CLIPBOARD_MESSAGE_RELEASE     = 2,
+  KVMFR_CLIPBOARD_MESSAGE_KEEPALIVE   = 3,
+  KVMFR_CLIPBOARD_MESSAGE_OFFER       = 4,
+  KVMFR_CLIPBOARD_MESSAGE_CLEAR       = 5,
+  KVMFR_CLIPBOARD_MESSAGE_REQUEST     = 6,
+  KVMFR_CLIPBOARD_MESSAGE_DATA        = 7,
+  KVMFR_CLIPBOARD_MESSAGE_COMMIT      = 8,
+  KVMFR_CLIPBOARD_MESSAGE_CANCEL      = 9,
+  KVMFR_CLIPBOARD_MESSAGE_ACK         = 10,
+  KVMFR_CLIPBOARD_MESSAGE_GRANT       = 11
+};
+
+typedef uint32_t KVMFRClipboardMessageType;
+
+enum
+{
+  KVMFR_CLIPBOARD_FLAG_BEGIN = 1U << 0,
+  KVMFR_CLIPBOARD_FLAG_END   = 1U << 1
+};
+
+typedef uint32_t KVMFRClipboardFlags;
+
+/*
+ * Bidirectional control record. Client-to-host records must fit LGMP's
+ * 64-byte client message area. Host-to-client records use a small payload
+ * pool and the same layout.
+ */
+typedef struct KVMFRClipboardMessage
+{
+  uint32_t                    version;
+  KVMFRClipboardMessageType   type;
+  uint32_t                    generation;
+  uint32_t                    sequence;
+  uint64_t                    clipboardGeneration;
+  uint64_t                    transfer;
+  uint64_t                    offset;
+  uint64_t                    size;
+  KVMFRClipboardFormat        format;
+  uint32_t                    flags;
+  uint32_t                    token;
+  uint32_t                    length;
+}
+KVMFRClipboardMessage;
+
+enum
+{
+  KVMFR_CLIPBOARD_STATUS_AVAILABLE = 1U << 0,
+  KVMFR_CLIPBOARD_STATUS_HAS_OWNER = 1U << 1
+};
+
+typedef uint32_t KVMFRClipboardStatusFlags;
+
+typedef struct KVMFRClipboardStatus
+{
+  uint32_t                     version;
+  KVMFRClipboardStatusFlags    flags;
+  uint32_t                     generation;
+  uint32_t                     ownerClientID;
+  uint32_t                     ownerGeneration;
+  uint32_t                     lease;
+  KVMFRClipboardFormatFlags    formats;
+  uint32_t                     slotBytes;
+}
+KVMFRClipboardStatus;
+
+/* The data immediately following this header is length bytes long. */
+typedef KVMFRClipboardMessage KVMFRClipboardSlotHeader;
+
+enum
+{
+  KVMFR_CLIPBOARD_QUEUE_STATUS  = 1,
+  KVMFR_CLIPBOARD_QUEUE_MESSAGE = 2,
+  KVMFR_CLIPBOARD_QUEUE_GRANT   = 3,
+  KVMFR_CLIPBOARD_QUEUE_DATA    = 4
+};
+
+typedef uint32_t KVMFRClipboardQueueType;
+
+#define KVMFR_CLIPBOARD_QUEUE_UDATA(type, serial) \
+  ((((uint64_t)(type)) << 32) | (uint32_t)(serial))
+#define KVMFR_CLIPBOARD_QUEUE_TYPE(udata) \
+  ((KVMFRClipboardQueueType)((uint64_t)(udata) >> 32))
+#define KVMFR_CLIPBOARD_QUEUE_SERIAL(udata) ((uint32_t)(udata))
+
+#if defined(__cplusplus)
+static_assert(sizeof(KVMFRClipboardMessage) == 64,
+  "KVMFR clipboard control message layout changed");
+static_assert(sizeof(KVMFRClipboardStatus) == 32,
+  "KVMFR clipboard status layout changed");
+static_assert(sizeof(KVMFRClipboardSlotHeader) == 64,
+  "KVMFR clipboard slot header layout changed");
+static_assert(sizeof(KVMFRClipboardMessage) <= 64,
+  "KVMFR clipboard message must fit one LGMP control message");
+#elif defined(__STDC_VERSION__) && __STDC_VERSION__ >= 201112L
+_Static_assert(sizeof(KVMFRClipboardMessage) == 64,
+  "KVMFR clipboard control message layout changed");
+_Static_assert(sizeof(KVMFRClipboardStatus) == 32,
+  "KVMFR clipboard status layout changed");
+_Static_assert(sizeof(KVMFRClipboardSlotHeader) == 64,
+  "KVMFR clipboard slot header layout changed");
+_Static_assert(sizeof(KVMFRClipboardMessage) <= 64,
+  "KVMFR clipboard message must fit one LGMP control message");
+#endif
+
+#endif

common/include/common/LGMPConfig.h

@@ -26,6 +26,7 @@
 // Base ID for LGMP_Q_FRAME_LEN independent owner-delivery queues.
 #define LGMP_Q_FRAME_OWNER 3
 #define LGMP_Q_INPUT       5
+#define LGMP_Q_CLIPBOARD   6
 
 // Two delivery lanes plus a spare buffer let the timing owner continue to
 // alternate buffers while a secondary client holds the shared delivery.
@@ -33,5 +34,6 @@
 #define LGMP_Q_FRAME_BUFFER_LEN 3
 #define LGMP_Q_POINTER_LEN      32
 #define LGMP_Q_INPUT_LEN        4
+#define LGMP_Q_CLIPBOARD_LEN    8
 
 #endif

idd/LGCommon/CClipboardRing.cpp

@@ -0,0 +1,116 @@
+/**
+ * Looking Glass
+ * Copyright © 2017-2026 The Looking Glass Authors
+ * https://looking-glass.io
+ *
+ * This program is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the Free
+ * Software Foundation; either version 2 of the License, or (at your option)
+ * any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+ * more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc., 59
+ * Temple Place, Suite 330, Boston, MA 02111-1307 USA
+ */
+
+#include "CClipboardRing.h"
+
+#include "Atomic.h"
+
+#include <string.h>
+
+void CClipboardRing::Initialize(
+  ClipboardMapping& mapping, uint64_t epoch)
+{
+  memset(&mapping, 0, sizeof(mapping));
+  mapping.magic     = LG_CLIPBOARD_MAPPING_MAGIC;
+  mapping.version   = LG_CLIPBOARD_MAPPING_VERSION;
+  mapping.size      = sizeof(mapping);
+  mapping.slotBytes = KVMFR_CLIPBOARD_DATA_BYTES;
+  mapping.slotCount = KVMFR_CLIPBOARD_SLOT_COUNT;
+  mapping.epoch     = epoch;
+}
+
+bool CClipboardRing::Valid(
+  const ClipboardMapping& mapping, uint64_t epoch)
+{
+  if (mapping.magic     != LG_CLIPBOARD_MAPPING_MAGIC   ||
+      mapping.version   != LG_CLIPBOARD_MAPPING_VERSION ||
+      mapping.size      != sizeof(mapping)               ||
+      mapping.slotBytes != KVMFR_CLIPBOARD_DATA_BYTES    ||
+      mapping.slotCount != KVMFR_CLIPBOARD_SLOT_COUNT    ||
+      !mapping.epoch || mapping.epoch != epoch)
+    return false;
+
+  ClipboardRing& helper =
+    const_cast<ClipboardRing&>(mapping.helperToIdd);
+  ClipboardRing& idd =
+    const_cast<ClipboardRing&>(mapping.iddToHelper);
+  const uint32_t helperProduced = Atomic::Load(helper.produced);
+  const uint32_t helperConsumed = Atomic::Load(helper.consumed);
+  const uint32_t iddProduced    = Atomic::Load(idd.produced);
+  const uint32_t iddConsumed    = Atomic::Load(idd.consumed);
+  return helperProduced - helperConsumed <= KVMFR_CLIPBOARD_SLOT_COUNT &&
+    iddProduced - iddConsumed <= KVMFR_CLIPBOARD_SLOT_COUNT;
+}
+
+ClipboardRingSlot * CClipboardRing::BeginWrite(
+  ClipboardRing& ring, uint32_t& ticket)
+{
+  const uint32_t produced = Atomic::Load(ring.produced);
+  const uint32_t consumed = Atomic::Load(ring.consumed);
+  const uint32_t pending = produced - consumed;
+  if (pending >= KVMFR_CLIPBOARD_SLOT_COUNT)
+    return nullptr;
+
+  ticket = produced;
+  return &ring.slots[produced % KVMFR_CLIPBOARD_SLOT_COUNT];
+}
+
+bool CClipboardRing::EndWrite(ClipboardRing& ring, uint32_t ticket)
+{
+  if (Atomic::Load(ring.produced) != ticket)
+    return false;
+
+  Atomic::Fence();
+  Atomic::Store(ring.produced, ticket + 1U);
+  return true;
+}
+
+const ClipboardRingSlot * CClipboardRing::BeginRead(
+  ClipboardRing& ring, uint32_t& ticket)
+{
+  const uint32_t consumed = Atomic::Load(ring.consumed);
+  const uint32_t pending = Atomic::Load(ring.produced) - consumed;
+  if (!pending || pending > KVMFR_CLIPBOARD_SLOT_COUNT)
+    return nullptr;
+
+  Atomic::Fence();
+  ticket = consumed;
+  return &ring.slots[consumed % KVMFR_CLIPBOARD_SLOT_COUNT];
+}
+
+bool CClipboardRing::EndRead(ClipboardRing& ring, uint32_t ticket)
+{
+  if (Atomic::Load(ring.consumed) != ticket)
+    return false;
+
+  Atomic::Fence();
+  Atomic::Store(ring.consumed, ticket + 1U);
+  return true;
+}
+
+bool CClipboardRing::Valid(const ClipboardRingSlot& slot)
+{
+  return slot.header.version == KVMFR_CLIPBOARD_VERSION &&
+    slot.header.type >= KVMFR_CLIPBOARD_MESSAGE_CLAIM &&
+    slot.header.type <= KVMFR_CLIPBOARD_MESSAGE_GRANT &&
+    slot.header.length <= KVMFR_CLIPBOARD_DATA_BYTES &&
+    (slot.header.type == KVMFR_CLIPBOARD_MESSAGE_DATA ||
+      !slot.header.length);
+}

idd/LGCommon/CClipboardRing.h

@@ -0,0 +1,40 @@
+/**
+ * Looking Glass
+ * Copyright © 2017-2026 The Looking Glass Authors
+ * https://looking-glass.io
+ *
+ * This program is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the Free
+ * Software Foundation; either version 2 of the License, or (at your option)
+ * any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+ * more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc., 59
+ * Temple Place, Suite 330, Boston, MA 02111-1307 USA
+ */
+
+#pragma once
+
+#include "ClipboardRing.h"
+
+class CClipboardRing
+{
+public:
+  static void Initialize(ClipboardMapping& mapping, uint64_t epoch);
+  static bool Valid(const ClipboardMapping& mapping, uint64_t epoch);
+
+  static ClipboardRingSlot * BeginWrite(
+    ClipboardRing& ring, uint32_t& ticket);
+  static bool EndWrite(ClipboardRing& ring, uint32_t ticket);
+
+  static const ClipboardRingSlot * BeginRead(
+    ClipboardRing& ring, uint32_t& ticket);
+  static bool EndRead(ClipboardRing& ring, uint32_t ticket);
+
+  static bool Valid(const ClipboardRingSlot& slot);
+};

idd/LGCommon/ClipboardRing.h

@@ -0,0 +1,64 @@
+/**
+ * Looking Glass
+ * Copyright © 2017-2026 The Looking Glass Authors
+ * https://looking-glass.io
+ *
+ * This program is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the Free
+ * Software Foundation; either version 2 of the License, or (at your option)
+ * any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+ * more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc., 59
+ * Temple Place, Suite 330, Boston, MA 02111-1307 USA
+ */
+
+#pragma once
+
+#include "common/KVMFRClipboard.h"
+
+#include <stddef.h>
+#include <stdint.h>
+
+static constexpr uint32_t LG_CLIPBOARD_MAPPING_MAGIC = 0x4c474342U;
+static constexpr uint32_t LG_CLIPBOARD_MAPPING_VERSION = 1U;
+
+struct ClipboardRingSlot
+{
+  KVMFRClipboardSlotHeader header;
+  uint8_t data[KVMFR_CLIPBOARD_DATA_BYTES];
+};
+
+struct alignas(64) ClipboardRing
+{
+  uint32_t produced;
+  uint32_t consumed;
+  uint32_t reserved[14];
+  ClipboardRingSlot slots[KVMFR_CLIPBOARD_SLOT_COUNT];
+};
+
+struct alignas(64) ClipboardMapping
+{
+  uint32_t magic;
+  uint32_t version;
+  uint32_t size;
+  uint32_t slotBytes;
+  uint32_t slotCount;
+  uint32_t reserved0;
+  uint64_t epoch;
+  uint8_t reserved1[32];
+  ClipboardRing helperToIdd;
+  ClipboardRing iddToHelper;
+};
+
+static_assert(sizeof(KVMFRClipboardSlotHeader) == 64,
+  "clipboard slot header alignment changed");
+static_assert(offsetof(ClipboardMapping, helperToIdd) == 64,
+  "clipboard mapping header layout changed");
+static_assert(offsetof(ClipboardMapping, iddToHelper) % 64 == 0,
+  "clipboard rings must remain cache-line aligned");

idd/LGCommon/LGCommon.vcxproj

@@ -65,13 +65,16 @@
     </ClCompile>
   </ItemDefinitionGroup>
   <ItemGroup>
+    <ClCompile Include="CClipboardRing.cpp" />
     <ClCompile Include="CDebug.cpp" />
     <ClCompile Include="CPipeEndpoint.cpp" />
     <ClCompile Include="RefreshRate.cpp" />
   </ItemGroup>
   <ItemGroup>
+    <ClInclude Include="CClipboardRing.h" />
     <ClInclude Include="Atomic.h" />
     <ClInclude Include="CDebug.h" />
+    <ClInclude Include="ClipboardRing.h" />
     <ClInclude Include="CPipeEndpoint.h" />
     <ClInclude Include="CSRWLock.h" />
     <ClInclude Include="DefaultDisplayModes.h" />

idd/LGCommon/LGCommon.vcxproj.filters

@@ -12,6 +12,9 @@
     </Filter>
   </ItemGroup>
   <ItemGroup>
+    <ClCompile Include="CClipboardRing.cpp">
+      <Filter>Source Files</Filter>
+    </ClCompile>
     <ClCompile Include="CDebug.cpp">
       <Filter>Source Files</Filter>
     </ClCompile>
@@ -26,9 +29,15 @@
     <ClInclude Include="Atomic.h">
       <Filter>Header Files</Filter>
     </ClInclude>
+    <ClInclude Include="CClipboardRing.h">
+      <Filter>Header Files</Filter>
+    </ClInclude>
     <ClInclude Include="CDebug.h">
       <Filter>Header Files</Filter>
     </ClInclude>
+    <ClInclude Include="ClipboardRing.h">
+      <Filter>Header Files</Filter>
+    </ClInclude>
     <ClInclude Include="CPipeEndpoint.h">
       <Filter>Header Files</Filter>
     </ClInclude>

idd/LGCommon/PipeMsg.h

@@ -39,7 +39,11 @@ struct LGPipeMsg
     RECOVERY_OFF,
     RECOVERY_ON,
     RECOVERY_FAILED,
-    RECOVERY_NO_DISPLAY
+    RECOVERY_NO_DISPLAY,
+    CLIPBOARD_SETUP,
+    CLIPBOARD_READY,
+    CLIPBOARD_KICK,
+    CLIPBOARD_RESET
   }
   type;
 
@@ -85,6 +89,34 @@ struct LGPipeMsg
       uint32_t request;
     }
     recovery;
+
+    struct
+    {
+      uint64_t handle;
+      uint32_t bytes;
+    }
+    clipboardSetup;
+
+    struct
+    {
+      uint64_t epoch;
+      uint32_t status;
+    }
+    clipboardReady;
+
+    struct
+    {
+      uint64_t epoch;
+      uint32_t rings;
+    }
+    clipboardKick;
+
+    struct
+    {
+      uint64_t epoch;
+      uint32_t reason;
+    }
+    clipboardReset;
   };
 };
 #pragma pack(pop)