diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/barrier.txt | 370 | ||||
| -rw-r--r-- | docs/devel/tracing.txt | 2 | ||||
| -rw-r--r-- | docs/nvdimm.txt | 31 | ||||
| -rw-r--r-- | docs/virtio-pmem.rst | 75 |
4 files changed, 478 insertions, 0 deletions
diff --git a/docs/barrier.txt b/docs/barrier.txt new file mode 100644 index 0000000000..b21d15015d --- /dev/null +++ b/docs/barrier.txt @@ -0,0 +1,370 @@ + 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 + +* 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 + - Manage SetOptions/ResetOptions commands + diff --git a/docs/devel/tracing.txt b/docs/devel/tracing.txt index 76e492a489..8231bbf5d1 100644 --- a/docs/devel/tracing.txt +++ b/docs/devel/tracing.txt @@ -112,6 +112,8 @@ Trace events should use types as follows: Format strings should reflect the types defined in the trace event. Take special care to use PRId64 and PRIu64 for int64_t and uint64_t types, respectively. This ensures portability between 32- and 64-bit platforms. +Format strings must not end with a newline character. It is the responsibility +of backends to adapt line ending for proper logging. Each event declaration will start with the event name, then its arguments, finally a format string for pretty-printing. For example: diff --git a/docs/nvdimm.txt b/docs/nvdimm.txt index b531cacd35..362e99109e 100644 --- a/docs/nvdimm.txt +++ b/docs/nvdimm.txt @@ -171,6 +171,35 @@ guest software that this vNVDIMM device contains a region that cannot accept persistent writes. In result, for example, the guest Linux NVDIMM driver, marks such vNVDIMM device as read-only. +Backend File Setup Example +-------------------------- + +Here are two examples showing how to setup these persistent backends on +linux using the tool ndctl [3]. + +A. DAX device + +Use the following command to set up /dev/dax0.0 so that the entirety of +namespace0.0 can be exposed as an emulated NVDIMM to the guest: + + ndctl create-namespace -f -e namespace0.0 -m devdax + +The /dev/dax0.0 could be used directly in "mem-path" option. + +B. DAX file + +Individual files on a DAX host file system can be exposed as emulated +NVDIMMS. First an fsdax block device is created, partitioned, and then +mounted with the "dax" mount option: + + ndctl create-namespace -f -e namespace0.0 -m fsdax + (partition /dev/pmem0 with name pmem0p1) + mount -o dax /dev/pmem0p1 /mnt + (create or copy a disk image file with qemu-img(1), cp(1), or dd(1) + in /mnt) + +Then the new file in /mnt could be used in "mem-path" option. + NVDIMM Persistence ------------------ @@ -212,3 +241,5 @@ References https://www.snia.org/sites/default/files/technical_work/final/NVMProgrammingModel_v1.2.pdf [2] Persistent Memory Development Kit (PMDK), formerly known as NVML project, home page: http://pmem.io/pmdk/ +[3] ndctl-create-namespace - provision or reconfigure a namespace + http://pmem.io/ndctl/ndctl-create-namespace.html diff --git a/docs/virtio-pmem.rst b/docs/virtio-pmem.rst new file mode 100644 index 0000000000..e77881b26f --- /dev/null +++ b/docs/virtio-pmem.rst @@ -0,0 +1,75 @@ + +======================== +QEMU virtio pmem +======================== + + This document explains the setup and usage of the virtio pmem device + which is available since QEMU v4.1.0. + + The virtio pmem device is a paravirtualized persistent memory device + on regular (i.e non-NVDIMM) storage. + +Usecase +-------- + + Virtio pmem allows to bypass the guest page cache and directly use + host page cache. This reduces guest memory footprint as the host can + make efficient memory reclaim decisions under memory pressure. + +o How does virtio-pmem compare to the nvdimm emulation supported by QEMU? + + NVDIMM emulation on regular (i.e. non-NVDIMM) host storage does not + persist the guest writes as there are no defined semantics in the device + specification. The virtio pmem device provides guest write persistence + on non-NVDIMM host storage. + +virtio pmem usage +----------------- + + A virtio pmem device backed by a memory-backend-file can be created on + the QEMU command line as in the following example: + + -object memory-backend-file,id=mem1,share,mem-path=./virtio_pmem.img,size=4G + -device virtio-pmem-pci,memdev=mem1,id=nv1 + + where: + - "object memory-backend-file,id=mem1,share,mem-path=<image>, size=<image size>" + creates a backend file with the specified size. + + - "device virtio-pmem-pci,id=nvdimm1,memdev=mem1" creates a virtio pmem + pci device whose storage is provided by above memory backend device. + + Multiple virtio pmem devices can be created if multiple pairs of "-object" + and "-device" are provided. + +Hotplug +------- + +Virtio pmem devices can be hotplugged via the QEMU monitor. First, the +memory backing has to be added via 'object_add'; afterwards, the virtio +pmem device can be added via 'device_add'. + +For example, the following commands add another 4GB virtio pmem device to +the guest: + + (qemu) object_add memory-backend-file,id=mem2,share=on,mem-path=virtio_pmem2.img,size=4G + (qemu) device_add virtio-pmem-pci,id=virtio_pmem2,memdev=mem2 + +Guest Data Persistence +---------------------- + + Guest data persistence on non-NVDIMM requires guest userspace applications + to perform fsync/msync. This is different from a real nvdimm backend where + no additional fsync/msync is required. This is to persist guest writes in + host backing file which otherwise remains in host page cache and there is + risk of losing the data in case of power failure. + + With virtio pmem device, MAP_SYNC mmap flag is not supported. This provides + a hint to application to perform fsync for write persistence. + +Limitations +------------ +- Real nvdimm device backend is not supported. +- virtio pmem hotunplug is not supported. +- ACPI NVDIMM features like regions/namespaces are not supported. +- ndctl command is not supported. |