# MMAP

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

## 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:

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