Graphics Sharing Parent topic: Graphics Sharing

vdev virtio-gpu

Updated: April 19, 2023

Provide GPU functionality and display-sharing capabilities to guests running in hypervisor VMs

Synopsis

vdev virtio-gpu
    [loc addr intr intr]
    gfxstream | virgl
    [render_options options]
    [vdisp [virtual_display1 options [: [virtual_display2 options]...]]]

Options

loc addr
Set the base address of the registers. This option, along with intr, is necessary only when you want to present the vdev as an MMIO device. See “Setting the guest interrupt” for more information.
intr intr
Specify the guest interrupt that is generated when the host or another guest sends a notification of an update to shared memory (e.g., gic:44). This option, along with loc, is necessary only when you want to present the vdev as an MMIO device. See “Setting the guest interrupt” for more information.
gfxstream
Use the virtual rendering library libgfxstream.so to support 3D rendering for OpenGL and Vulkan.

For Android guests, you must specify this option or virgl, because Android can't operate in 2D mode. For guests that can operate in 2D mode, using one of these libraries is optional. For any guest type, to use Address Space Graphics (ASG) mode with gfxstream, the vdev must be presented as an MMIO device, meaning loc and intr must be defined also.

virgl
Use the virtual rendering library libvirglrenderer.so to support 3D rendering for OpenGL only.

For Android guests, you must specify this option or gfxstream, because Android can't operate in 2D mode. For guests that can operate in 2D mode, using one of these libraries is optional.

render_options options
Specify options that affect rendering, as a comma-separated list of strings. Some options must be prefixed by a dash (-) but others don't require it. The expected syntax is shown for all supported rendering options. These options include:
api=[gles|vulkan]
The backend renderer API, either OpenGLES or Vulkan. If this option is omitted, a default mix of these APIs is used. This option should be set to gles when Vulkan libraries are not available on the host.
-debug=level
The verbosity level. The level can be any severity level supported by slog2info.
-enable_gl_presenter=0|1
Whether to enable the GL presenter.

By default, this option is disabled.

enable_gles_3_1=0|1
By default, GFXStream operates in OpenGL ES 3.0. Enabling this option enables OpenGL ES 3.1, but this is valid only if the host system supports version 3.1. Otherwise, the guest will operate at a lower API version.

By default, this option is disabled.

-force_gl_presenter=0|1
Whether to force the GL presenter to take over. Setting this option implicitly enables the GL presenter.

By default, this option is disabled.

-force_glsl_version=version
The OpenGL Shading Language (GLSL) version that VirGL is forced to use. Accepted values are 120, 300, 310, and 330.

This is useful to make the guest operate in a lower OpenGL ES API version. For instance, it can force the guest to operate in OpenGL ES 2.0 on a host that supports OpenGL ES 3.0.

-runmask=mask
The active CPU cores. The mask argument is a bitfield in which the bits for active cores are set; for instance, 0x30 means cores 4 and 5 are active. The default value is 0, meaning no active cores are set.
vram_loc=address
The start of the guest-physical address range to search for available space to store the shared memory region. The address can be specified in decimal or hexadecimal; in the latter case, it begins with 0x. The default is 0x0.

This option provides a hint about which guest-physical address range the shared memory should be mapped into. But if the shared memory can't be mapped into this range, no error is issued. Also, this feature is needed only when you're using the GFXStream library and you've configured ASG mode for this library (in the qvm configuration file).

When this rendering option and/or vram_size is set, you must also set loc and intr so the vdev presents itself as an MMIO device.

vram_size=size
The size of the shared memory region reserved on the guest. The argument is a number optionally followed by a K, M, or G character (case insensitive). The default is 1024M (1024 MB).

The shared memory feature is needed only when you're using the GFXStream library and you've configured ASG mode for this library (in the qvm configuration file).

When this rendering option and/or vram_loc is set, you must also set loc and intr so the vdev presents itself as an MMIO device.

vdisp [virtual_display1_options [: [virtual_display2_options]...]]
Specify the virtual displays with their associated options so that guests can share image content to be shown on physical displays. You can configure multiple virtual displays to show content on the same physical display or on different physical displays on the host.

Each virtual display is defined by its name followed by a list of options (as name-value pairs) and a colon (:), which separates it from other virtual displays. Different options within a list must be separated by a comma (,).

You can specify the following options for each virtual display:
-bsize=buffer_widthxbuffer_height
Optionally specify the size (in pixels) of the buffer of the Screen window that's associated with the virtual display. This is the size of the buffer that guests have access to when creating their virtual display/framebuffer.

If not specified, the size of the buffer is set to the -size= option or to fullscreen.

-class_name=class_name
Specify the name (as a string) of the window class to use to assign window property values.

The class_name must be a valid class that you have defined in your graphics configuration file (e.g., graphics.conf) on the host. Screen applies the properties that you've specified in the configuration file for class_name to the Screen window that's associated with the virtual display.

If not specified, Screen applies the default values corresponding to each of the window properties.

-disp_id=display_id
Specify the physical display ID (as an integer) that's associated with the virtual display. The display_id value must refer to a valid display that's attached to the host.

If you are defining multiple virtual displays, you must minimally include -disp_id= in the list of options.

If this option is not specified, Screen uses its default display.

-grp_name=window_group_name
Specify the window group (as a string) that the Screen window that's associated with the virtual display is to join.

The window_group_name value must be a valid window group on your host.

-pos=x_positionxy_position
Specify the x and y positions of the top-left corner of the Screen window that's associated with the virtual display. The two values are separated by an x (“ex”).

If not specified, the default position is 0x0.

-size=display_widthxdisplay_height
Specify the size (in pixels) of the Screen window that's associated with the virtual display.

If not specified, the size of the window is set to fullscreen.

-win_type=window_type
Specify the type (as a string) of the Screen window that's associated with the virtual display. The following window_type values are allowed:
Type specified Screen window type
em SCREEN_EMBEDDED_WINDOW
ch SCREEN_CHILD_WINDOW
ap SCREEN_APPLICATION_WINDOW

If not specified, the window type is set to SCREEN_APPLICATION_WINDOW.

Description

This vdev is a para-virtualized device that enables graphics sharing in hypervisor systems by providing:
  • guest OS access to functionality that would be provided by the GPU in a non-virtualized environment
  • guest OS access to virtual displays through which the guest can share image content with the host, to show this content on a physical display

You must specify vdev virtio-gpu with the appropriate options in the configuration file (*.qvmconf) for the guest. For more information, see “Common vdev options” in the QNX Hypervisor User's Guide.

For Android guests, you must provide either the gfxstream or virgl vdev option, to indicate which virtual rendering library you will use for 3D rendering. This is because these guests can't operate in 2D, unlike some other guests.

Examples

Sharing the GPU
To configure the virtio-gpu vdev for GPU sharing only and to use libvirglrenderer.so for 3D rendering, you may use the following configuration: 
vdev virtio-gpu
  virgl
  render-options -force_gl_presenter=1,-force_glsl_version=120
Sharing displays
To configure the vdev for GPU and display sharing, you may try the following configurations:
  • Select libgfxstream.so for 3D rendering and configure one virtual display (named vdisp) for a guest to show content on the default display on the host: 
    vdev virtio-gpu
  loc 0x1c160000
  intr gic:63
  gfxstream
  render_options -force_gl_presenter=1,enable_gles_3_1=1,\
    vram_loc=0x300010000
  vdisp
    Note: When you're using GFXStream in ASG mode, the loc and intr options must be defined because the device must be an MMIO device. The vram_loc and vram_size rendering options (the latter not used in this example) can also be defined to configure the shared memory.

    When you're using pipe mode, the device can be either an MMIO or a PCI device. In the latter case, you don't need any of these options.

  • Use libgfxstream.so and configure two virtual displays for a guest to show content on the same physical display on the host: 
    vdev virtio-gpu
  loc 0x1c160000
  intr gic:63
  gfxstream
  render_options -force_gl_presenter=1,enable_gles_3_1=1,\
    vram_loc=0x300010000
  vdisp -disp_id=1,-bsize=1280x720,-size=640x720,-pos=0x0 : \
    -disp_id=1,-bsize=1280x720,-size=640x720,-pos=640x0
  • Use libgfxstream.so and configure two virtual displays for a guest to show content on two different physical displays on the host: 
    vdev virtio-gpu
  loc 0x1c160000
  intr gic:63
  gfxstream
  render_options -force_gl_presenter=1,enable_gles_3_1=1,\
    vram_loc=0x300010000
  vdisp -disp_id=1 : -disp_id=2
Parent topic: Graphics Sharing