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.

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

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.

The client does not get to choose which directory the server opens the file from: the server only uses the basename of the file attribute, and looks for it in one of the directories it accepts. Unless directories have been specified with the mmap option, these are the server's own mmap directory and, when the peer can be identified as another local user, that user's mmap directory. Clients specifying a file anywhere else are refused and mmap is then disabled.

The file is opened relative to that directory and symbolic links are never followed, then the file descriptor itself is verified rather than the path: it must be a regular file, with a single link, belonging either to the server or to the client's user. The directory must not be writable by everyone unless the sticky bit prevents other users from replacing files in it. None of these checks apply to a path specified with the mmap option: that one is chosen by the administrator and can legitimately be a symbolic link, a device file, or a file belonging to another user.

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.

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

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:

• qemu ivshmem device
• ivshmem-spec
• mmap support for --bind-vsock (and --bind-tcp)
• add documentation for virtio-shmem mmap usage