vdev shmem

Synopsis:

vdev shmem options

Options:

allow fnpattern

Allow the guest to create or attach to any shared memory region whose name matches the specified filename pattern (fnpattern).

In this string argument, you can use the same wildcards as the shell uses for filename expansion, including asterisks (*). You can repeat this option as much as necessary to grant the guest access to shared memory.

If you use this option at all, the configuration will include an implicit deny * at the end of the restrictions list, and the guest will be denied access to all shared memory regions not specified by this list. For example:

vdev shmem
    allow test*
    allow pluto

grants the guest access to any shared memory region whose name begins with test and to the region called pluto. The guest is denied access to all other regions.

These semantics mean you need to use one (but not both) of the allow or deny options. For further discussion, see Restrictions list below.

create name,size[,mode[,gid]]

Pre-create a shared memory object named name of size bytes. You can optionally define the POSIX permissions with mode and group ownership with gid, which can be a group name or ID.

The default permissions setting is 0666, but this can be overriden by a preceding umask option. The group ownership defaults to the effective group ID of the qvm process, unless a preceding gid option has been provided. For the create option, the gid argument can be specified only if the mode argument is also specified.

You can repeat the create option to pre-create multiple shared memory regions.

deny fnpattern

Deny the guest access to any shared memory region whose name matches the specified filename pattern (fnpattern).

In this string argument, you can use the same wildcards as the shell uses for filename expansion, including asterisks (*). You can repeat this option as much as necessary to restrict the guest's access to shared memory.

If you use this option at all, the configuration will include an implicit allow * at the end of the restrictions list, and the guest will be granted access to all shared memory regions not specified by this list. For example:

vdev shmem
    deny live*
    deny pluto

denies the guest access to any shared memory region whose name begins with live and to the region called pluto. The guest can access any other shared memory region, however.

These semantics mean you need to use one (but not both) of the allow or deny options. For further discussion, see Restrictions list below.

Alternatively, after using create directives to pre-create specific named shared memory regions, you can use a deny * directive to deny access to all other regions.

gid name|id

Set the group ownership of shared memory regions created by this vdev instance to the group indicated by name or id. Any subsequent create options will use this setting by default.

intr intr

If the loc option is specified, you must also specify the value of intr; this sets the guest interrupt that is generated when another guest sends a notification of an update to shared memory.

loc [addr]

The base address of the factory page for the vdev. If addr isn't specified, the vdev appears as a PCI device, and the qvm process automatically assigns the factory page location and adds this location to the PCI BAR register.

If you specify this option, you must also specify the intr option (see above).

sched priority

Use the specified priority for pulses indicating that input is available.

subst [original],prefix

Specify a prefix to add to shared memory region names seen by the host (for more details, see Using the subst option below).

original

The character string in the original name of the shared memory region to substitute, if found, by the character string given by prefix.

prefix

The character string to substitute for the character string specified by original, or to simply prefix to the name of the shared memory region if original isn't specified.

umask permissions

Define permission bits to remove from the set provided by the guest. This option defaults to 0 for backwards compatibility. Any subsequent create options are affected by the value given to this umask option. Note that the execute bits are never set—the shared memory region has a header that is not visible to the guest which makes it unsuitable as an executable binary.

For a list of options available to all vdevs, see Common vdev options at the beginning of this chapter.

Description:

ARM and x86. The shmem vdev allows you to share memory between different guests or between guests and the host. Normally this device appears as a PCI device, but if the loc and intr options are specified, the guest running in the associated VM will see this device as a memory-mapped I/O (MMIO) device at the specified location.

Restrictions list

You can use the allow and deny options to define lists of shared memory regions that the guest may or may not access. By limiting access to shared memory and, hence, allocations of shared memory, these options help prevent denial-of-service attacks.

You can repeat either of these options multiple times to specify whatever filename patterns you need to manage the guest's access to shared memory regions. When specifying filename patterns, you can include wildcard characters such as the asterisk (*) to indicate multiple shared memory regions for convenience. We recommend defining either an allow or a deny policy for every named region used by the VM, including when using wildcard naming.

For more information about using the shared memory vdev, see Memory sharing in the Using Virtual Devices, Networking, and Memory Sharing chapter.

Using the subst option

You can use this option to present the host with different names for shared memory regions for each guest, while presenting the same name to each guest so you can use the same executables in the different guests. For example, each guest might see a shared region called foomem, but the host would see these regions as guest0mem, guest1mem, etc.

The following VM configurations produce the result presented above by substituting guest* for foo:

VM 0

vdev shmem
    subst foo,guest0
    create foomem,0xf0000
    ...

VM 1

vdev shmem
    subst foo,guest1
    ...

An equivalent result can be achieved by simply adding the guest* prefix, as follows:

VM 0

vdev shmem
    subst ,guest0
    create mem,0xf0000
    ...

VM 1

vdev shmem
    subst ,guest1
    ...