F OpenNebula/one#6286: documentation for VIDEO attribute

Signed-off-by: Neal Hansen <[email protected]>
OpenNebula · Sep 15, 2023 · 24264d3 · 24264d3
1 parent 4903bb0
commit 24264d3
Show file tree

Hide file tree

Showing 4 changed files with 35 additions and 6 deletions.
diff --git a/source/integration_and_development/system_interfaces/api.rst b/source/integration_and_development/system_interfaces/api.rst
@@ -2099,6 +2099,8 @@ The supported attributes are:
 +--------------+-------------------------------------------------------------------------+
 | ``GRAPHICS`` | ``TYPE``, ``LISTEN``, ``PASSWD``, ``KEYMAP``                            |
 +--------------+-------------------------------------------------------------------------+
+| ``VIDEO``    | ``TYPE``, ``IOMMU``, ``ATS``, ``VRAM``, ``RESOLUTION``                  |
++--------------+-------------------------------------------------------------------------+
 | ``RAW``      | ``DATA``, ``DATA_VMX``, ``TYPE``                                        |
 +--------------+-------------------------------------------------------------------------+
 | ``CONTEXT``  | Any value. **Variable substitution will be made**                       |

diff --git a/source/management_and_operations/references/template.rst b/source/management_and_operations/references/template.rst
@@ -599,17 +599,30 @@ The following I/O interfaces can be defined for a VM:
 | ``GRAPHICS`` | Wether the VM should export its graphical display and how, available sub-attributes: | O   | O       | O       | O           |
 |              |                                                                                      |     |         |         |             |
 |              +--------------------------------------------------------------------------------------+-----+---------+---------+-------------+
-|              | * ``TYPE``: values: ``vnc``, ``sdl``, ``spice``.                                     |     |         | O (vnc) | O (vnc)     |
+|              | * ``TYPE``: values: ``vnc``, ``sdl``, ``spice``.                                     | O   | O       | O (vnc) | O (vnc)     |
 |              +--------------------------------------------------------------------------------------+-----+---------+---------+-------------+
-|              | * ``LISTEN``: IP to listen on.                                                       |     |         | O       | O           |
+|              | * ``LISTEN``: IP to listen on.                                                       | O   | O       | O       | O           |
 |              +--------------------------------------------------------------------------------------+-----+---------+---------+-------------+
-|              | * ``PORT``: port for the VNC server.                                                 |     |         | O       | O           |
+|              | * ``PORT``: port for the VNC server.                                                 | O   | O       | O       | O           |
 |              +--------------------------------------------------------------------------------------+-----+---------+---------+-------------+
-|              | * ``PASSWD``\ :sup:`*`: password for the VNC server.                                 |     |         | O       | O           |
+|              | * ``PASSWD``\ :sup:`*`: password for the VNC server.                                 | O   | O       | O       | O           |
 |              +--------------------------------------------------------------------------------------+-----+---------+---------+-------------+
-|              | * ``KEYMAP``: keyboard configuration locale to use in the VNC display.               |     |         | \-      | \-          |
+|              | * ``KEYMAP``: keyboard configuration locale to use in the VNC display.               | O   | O       | \-      | \-          |
 |              +--------------------------------------------------------------------------------------+-----+---------+---------+-------------+
-|              | * ``RANDOM_PASSWD``: if "YES", generate a random password for each VM.               |     |         | O       | O           |
+|              | * ``RANDOM_PASSWD``: if "YES", generate a random password for each VM.               | O   | O       | O       | O           |
++--------------+--------------------------------------------------------------------------------------+-----+---------+---------+-------------+
+| ``VIDEO``    | Defines a custom video device, available sub-attributes:                             | O   | \-      | \-      | \-          |
+|              |                                                                                      |     |         |         |             |
+|              +--------------------------------------------------------------------------------------+-----+---------+---------+-------------+
+|              | * ``TYPE``: values: ``none``, ``vnc``, ``cirrus``, and ``virtio``                    | M   | \-      | \-      | \-          |
+|              +--------------------------------------------------------------------------------------+-----+---------+---------+-------------+
+|              | * ``IOMMU``: Enables the use of emulated IOMMU by the video device.                  | O   | \-      | \-      | \-          |
+|              +--------------------------------------------------------------------------------------+-----+---------+---------+-------------+
+|              | * ``ATS``: Enables Address Translate Service for the device.                         | O   | \-      | \-      | \-          |
+|              +--------------------------------------------------------------------------------------+-----+---------+---------+-------------+
+|              | * ``VRAM``: Defines the amount of VRAM for the device, in kB                         | O   | \-      | \-      | \-          |
+|              +--------------------------------------------------------------------------------------+-----+---------+---------+-------------+
+|              | * ``RESOLUTION``: The preferred device resolution(ex: "1920x1080", "1280x768")       | O   | \-      | \-      | \-          |
 +--------------+--------------------------------------------------------------------------------------+-----+---------+---------+-------------+
 
 \ :sup:`*` Password will be truncated if its length exceeds 8 characters for ``vnc`` or 60 characters for ``spice``.

diff --git a/source/management_and_operations/vm_management/vm_instances.rst b/source/management_and_operations/vm_management/vm_instances.rst
@@ -532,6 +532,8 @@ Some of the VM configuration attributes defined in the VM Template can be update
 +-------------------+-------------------------------------------------------------------------+
 | ``GRAPHICS``      | ``TYPE``, ``LISTEN``, ``PASSWD``, ``KEYMAP``                            |
 +-------------------+-------------------------------------------------------------------------+
+| ``VIDEO``         | ``TYPE``, ``IOMMU``, ``ATS``, ``VRAM``, ``RESOLUTION``                  |
++-------------------+-------------------------------------------------------------------------+
 | ``RAW``           | ``DATA``, ``DATA_VMX``, ``TYPE``                                        |
 +-------------------+-------------------------------------------------------------------------+
 | ``CPU_MODEL``     | ``MODEL``                                                               |

diff --git a/source/open_cluster_deployment/kvm_node/kvm_driver.rst b/source/open_cluster_deployment/kvm_node/kvm_driver.rst
@@ -44,6 +44,7 @@ There are some attributes required for KVM to boot a VM. You can set a suitable
 * ``DISK``: attributes ``DRIVER``, ``CACHE``, ``IO``, ``DISCARD``, ``TOTAL_BYTES_SEC``, ``TOTAL_IOPS_SEC``, ``READ_BYTES_SEC``, ``WRITE_BYTES_SEC``, ``READ_IOPS_SEC``, ``WRITE_IOPS_SEC``, ``SIZE_IOPS_SEC``.
 * ``NIC``: attribute ``FILTER``, ``MODEL``.
 * ``GRAPHICS``: attributes ``TYPE``, ``LISTEN``, ``PASSWD``, ``KEYMAP``, ``RANDOM_PASSWD``. The VM instance must have at least empty ``GRAPHICS = []`` section to read these default attributes from the config file and to generate cluster unique ``PORT`` attribute.
+* ``VIDEO``: attributes: ``TYPE``, ``IOMMU``, ``ATS``, ``VRAM``, ``RESOLUTION``.
 * ``RAW``: to add libvirt attributes to the domain XML file.
 * ``HYPERV_OPTIONS``: to enable hyperv extensions.
 * ``SPICE_OPTIONS``: to add default devices for SPICE.
@@ -182,6 +183,17 @@ If properly configured, libvirt and KVM can work with SPICE (`check here for mor
 
 Enabling spice will also make the driver inject a specific configuration for these machines. The configuration can be changed in the driver configuration file, variable ``SPICE_OPTIONS``.
 
+Video
+~~~~~
+
+If configured, libvirt will attach a video device to the virtual machine with the specified attributes. Available attributes are:
+
+* ``TYPE``: Defines the device type. Can be ``none``, ``vga``, ``cirrus``, and ``virtio``.  Utilizing ``virtio`` is required for ``IOMMU`` an ``ATS`` options.
+* ``IOMMU``: Enables the device to use emulated IOMMU.  Requires ``virtio`` type.
+* ``ATS``: Enables the device to use Address Translation Service.  Requires ``virtio`` type.
+* ``VRAM``: Defines the amount of VRAM to allocate to the video device, in kB.
+* ``RESOLUTION``: Defines the preferred resolution of the video device. Should be two numbers separated by an ``x``. Example: ``1920x1080``
+
 .. _kvmg_virtio:
 
 Virtio