MMAP

The mmap modules are used for fast memory transfers between client and server when both reside on the same host.

The client creates its mmap areas before the connection is established, so it cannot know yet whether the server will be able to use them. On MS Windows, where the areas are charged to the system commit limit as soon as they are created and the server is very rarely local, the default value of the mmap option (auto) therefore means no: it must be enabled explicitly with mmap=yes.

Implementations

The prefix for all packets and capabilities is mmap.

| Component | Link | |-------------------|----------------------------------------------------------------------------------------------------------| | client | xpra.client.subsystem.mmap | | client connection | xpra.server.source.mmap | | server | xpra.server.subsystem.mmap |

Capabilities

The client and server should expose the following capabilities in their hello packet using the clipboard prefix.

The client creates an mmap backing file for each direction it wants to use:

read for receiving data from the server
write for sending data to the server

For each capability, the client writes a random token at a random position within this mmap area and sends the following attributes:

| Capability | Value | |---------------|--------------------------------------| | file | path to the mmap backing file | | size | size of the mmap area | | token | random token value generated | | token_index | position where the token was written | | token_bytes | length of the token in bytes |

The server should attempt to open the mmap file specified, and verify that the token is found.

To use this mmap file, it must write a new token and return this information to the client. (using the same format, excluding the file and size that the client has already specified)

The client then verifies that the mmap file can be used.

Network Packets

There are no specific mmap packets used, mmap is used as an encoding.

virtio-shmem

Xpra can use mmap with virtio-shmem to speed up connections between a host and guest or even between two guests.

Example steps for host to guest setup:

add a shmem device to your VM, ie:

DEV_NAME="shmem-xpra"
virt-install --shmem name="${DEV_NAME}",model.type=ivshmem-plain,size.unit=M,size=512"`)

enable the shared memory device on the guest:

echo 1 > $(find /sys/devices/ -type f -name "resource2_wc" -exec dirname "{}" \;)/enable

and start an xpra server with mmap pointing to it:

VSOCK_PORT=10000
MMAP_PATH=$(find /sys/devices/ -type f -name "resource2_wc")
xpra seamless --bind-vsock=auto:${VSOCK_PORT} --mmap=$MMAP_PATH

from the host, use mmap with the same device:

DEV_NAME="shmem-xpra"
VSOCK_PORT=10000
VM_CID=$(virsh dumpxml "${DEV_NAME}" | grep cid | sed 's/[^0-9]*//g')
xpra attach vsock://"${VM_CID}":${VSOCK_PORT}/ -d mmap --mmap="/dev/shm/${DEV_NAME}"

Documentation: