From 4602f20e624524d9a409b0be02c9a7a93530be89 Mon Sep 17 00:00:00 2001 From: Geoffrey McRae Date: Fri, 14 Aug 2026 04:05:15 +1000 Subject: [PATCH] [common] clipboard: define streamed clipboard ABIs --- common/include/common/KVMFR.h | 4 +- common/include/common/KVMFRClipboard.h | 183 +++++++++++++++++++++++++ common/include/common/LGMPConfig.h | 2 + idd/LGCommon/CClipboardRing.cpp | 116 ++++++++++++++++ idd/LGCommon/CClipboardRing.h | 40 ++++++ idd/LGCommon/ClipboardRing.h | 64 +++++++++ idd/LGCommon/LGCommon.vcxproj | 3 + idd/LGCommon/LGCommon.vcxproj.filters | 9 ++ idd/LGCommon/PipeMsg.h | 34 ++++- 9 files changed, 453 insertions(+), 2 deletions(-) create mode 100644 common/include/common/KVMFRClipboard.h create mode 100644 idd/LGCommon/CClipboardRing.cpp create mode 100644 idd/LGCommon/CClipboardRing.h create mode 100644 idd/LGCommon/ClipboardRing.h diff --git a/common/include/common/KVMFR.h b/common/include/common/KVMFR.h index 1399a849..a9ece7c6 100644 --- a/common/include/common/KVMFR.h +++ b/common/include/common/KVMFR.h @@ -28,6 +28,7 @@ #include #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; diff --git a/common/include/common/KVMFRClipboard.h b/common/include/common/KVMFRClipboard.h new file mode 100644 index 00000000..5b5193ec --- /dev/null +++ b/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 +#include + +#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 diff --git a/common/include/common/LGMPConfig.h b/common/include/common/LGMPConfig.h index 698dea92..f88ac621 100644 --- a/common/include/common/LGMPConfig.h +++ b/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 diff --git a/idd/LGCommon/CClipboardRing.cpp b/idd/LGCommon/CClipboardRing.cpp new file mode 100644 index 00000000..943dd285 --- /dev/null +++ b/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 + +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(mapping.helperToIdd); + ClipboardRing& idd = + const_cast(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); +} diff --git a/idd/LGCommon/CClipboardRing.h b/idd/LGCommon/CClipboardRing.h new file mode 100644 index 00000000..44a910d8 --- /dev/null +++ b/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); +}; diff --git a/idd/LGCommon/ClipboardRing.h b/idd/LGCommon/ClipboardRing.h new file mode 100644 index 00000000..7f028a90 --- /dev/null +++ b/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 +#include + +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"); diff --git a/idd/LGCommon/LGCommon.vcxproj b/idd/LGCommon/LGCommon.vcxproj index c331f8ab..ea941284 100644 --- a/idd/LGCommon/LGCommon.vcxproj +++ b/idd/LGCommon/LGCommon.vcxproj @@ -65,13 +65,16 @@ + + + diff --git a/idd/LGCommon/LGCommon.vcxproj.filters b/idd/LGCommon/LGCommon.vcxproj.filters index 4a003b07..37aa7b57 100644 --- a/idd/LGCommon/LGCommon.vcxproj.filters +++ b/idd/LGCommon/LGCommon.vcxproj.filters @@ -12,6 +12,9 @@ + + Source Files + Source Files @@ -26,9 +29,15 @@ Header Files + + Header Files + Header Files + + Header Files + Header Files diff --git a/idd/LGCommon/PipeMsg.h b/idd/LGCommon/PipeMsg.h index 494f804a..376780c0 100644 --- a/idd/LGCommon/PipeMsg.h +++ b/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)