[PATCH 20/32] docs: formatdomain-devices: Split out <videO>
Peter Krempa
pkrempa at redhat.com
Thu Jul 23 13:21:25 UTC 2020
Signed-off-by: Peter Krempa <pkrempa at redhat.com>
---
docs/formatdomain-devices-video.rst | 101 +++++++++++++++++++++++++++
docs/formatdomain-devices.rst | 103 +---------------------------
docs/meson.build | 1 +
3 files changed, 103 insertions(+), 102 deletions(-)
create mode 100644 docs/formatdomain-devices-video.rst
diff --git a/docs/formatdomain-devices-video.rst b/docs/formatdomain-devices-video.rst
new file mode 100644
index 0000000000..54f84a1a8a
--- /dev/null
+++ b/docs/formatdomain-devices-video.rst
@@ -0,0 +1,101 @@
+:anchor:`<a id="elementsVideo"/>`
+
+Video devices
+~~~~~~~~~~~~~
+
+A video device.
+
+::
+
+ ...
+ <devices>
+ <video>
+ <model type='vga' vram='16384' heads='1'>
+ <acceleration accel3d='yes' accel2d='yes'/>
+ </model>
+ <driver name='qemu'/>
+ </video>
+ </devices>
+ ...
+
+``video``
+ The ``video`` element is the container for describing video devices. For
+ backwards compatibility, if no ``video`` is set but there is a ``graphics``
+ in domain xml, then libvirt will add a default ``video`` according to the
+ guest type.
+
+ For a guest of type "kvm", the default ``video`` is: ``type`` with value
+ "cirrus", ``vram`` with value "16384" and ``heads`` with value "1". By
+ default, the first video device in domain xml is the primary one, but the
+ optional attribute ``primary`` ( :since:`since 1.0.2` ) with value 'yes' can
+ be used to mark the primary in cases of multiple video device. The
+ non-primary must be type of "qxl" or ( :since:`since 2.4.0` ) "virtio".
+
+``model``
+ The ``model`` element has a mandatory ``type`` attribute which takes the
+ value "vga", "cirrus", "vmvga", "xen", "vbox", "qxl" ( :since:`since 0.8.6`
+ ), "virtio" ( :since:`since 1.3.0` ), "gop" ( :since:`since 3.2.0` ), "bochs"
+ ( :since:`since 5.6.0` ), "ramfb" ( :since:`since 5.9.0` ), or "none" (
+ :since:`since 4.6.0` , depending on the hypervisor features available. The
+ purpose of the type ``none`` is to instruct libvirt not to add a default
+ video device in the guest (see the paragraph above). This legacy behaviour
+ can be inconvenient in cases where GPU mediated devices are meant to be the
+ only rendering device within a guest and so specifying another ``video``
+ device along with type ``none``. Refer to Host device assignment to see how
+ to add a mediated device into a guest.
+
+ You can provide the amount of video memory in kibibytes (blocks of 1024
+ bytes) using ``vram``. This is supported only for guest type of "vz", "qemu",
+ "vbox", "vmx" and "xen". If no value is provided the default is used. If the
+ size is not a power of two it will be rounded to closest one.
+
+ The number of screen can be set using ``heads``. This is supported only for
+ guests type of "vz", "kvm", "vbox" and "vmx".
+
+ For guest type of "kvm" or "qemu" and model type "qxl" there are optional
+ attributes. Attribute ``ram`` ( :since:` since 1.0.2` ) specifies the size of
+ the primary bar, while the attribute ``vram`` specifies the secondary bar
+ size. If ``ram`` or ``vram`` are not supplied a default value is used. The
+ ``ram`` should also be rounded to power of two as ``vram``. There is also
+ optional attribute ``vgamem`` ( :since:`since 1.2.11` ) to set the size of
+ VGA framebuffer for fallback mode of QXL device. Attribute ``vram64`` (
+ :since:`since 1.3.3` ) extends secondary bar and makes it addressable as
+ 64bit memory.
+
+ :since:`Since 5.9.0` , the ``model`` element may also have an optional
+ ``resolution`` sub-element. The ``resolution`` element has attributes ``x``
+ and ``y`` to set the minimum resolution for the video device. This
+ sub-element is valid for model types "vga", "qxl", "bochs", and "virtio".
+
+``acceleration``
+ Configure if video acceleration should be enabled.
+
+ ``accel2d``
+ Enable 2D acceleration (for vbox driver only, :since:`since 0.7.1` )
+ ``accel3d``
+ Enable 3D acceleration (for vbox driver :since:`since 0.7.1` , qemu driver
+ :since:`since 1.3.0` )
+ ``rendernode``
+ Absolute path to a host's DRI device to be used for rendering (for
+ 'vhostuser' driver only, :since:`since 5.8.0` ). If none is specified,
+ libvirt will pick one available.
+
+``address``
+ The optional ``address`` sub-element can be used to tie the video device to a
+ particular PCI slot. On S390, ``address`` can be used to provide the CCW
+ address for the video device ( :since:` since 4.2.0` ).
+``driver``
+ The subelement ``driver`` can be used to tune the device:
+
+ ``name``
+ Specify the backend driver to use, either "qemu" or "vhostuser" depending
+ on the hypervisor features available ( :since:`since 5.8.0` ). "qemu" is
+ the default QEMU backend. "vhostuser" will use a separate vhost-user
+ process backend (for ``virtio`` device).
+ virtio options
+ `Virtio-specific options <#elementsVirtio>`__ can also be set (
+ :since:`Since 3.5.0` )
+ VGA configuration
+ Control how the video devices exposed to the guest using the ``vgaconf``
+ attribute which takes the value "io", "on" or "off". At present, it's only
+ applicable to the bhyve's "gop" video model type ( :since:`Since 3.5.0` )
diff --git a/docs/formatdomain-devices.rst b/docs/formatdomain-devices.rst
index d2aba7ba28..8d8d52731e 100644
--- a/docs/formatdomain-devices.rst
+++ b/docs/formatdomain-devices.rst
@@ -52,108 +52,7 @@ following characters: ``[a-zA-Z0-9_-]``. :since:`Since 3.9.0`
.. include:: formatdomain-devices-input.rst
.. include:: formatdomain-devices-hub.rst
.. include:: formatdomain-devices-graphics.rst
-
-:anchor:`<a id="elementsVideo"/>`
-
-Video devices
-~~~~~~~~~~~~~
-
-A video device.
-
-::
-
- ...
- <devices>
- <video>
- <model type='vga' vram='16384' heads='1'>
- <acceleration accel3d='yes' accel2d='yes'/>
- </model>
- <driver name='qemu'/>
- </video>
- </devices>
- ...
-
-``video``
- The ``video`` element is the container for describing video devices. For
- backwards compatibility, if no ``video`` is set but there is a ``graphics``
- in domain xml, then libvirt will add a default ``video`` according to the
- guest type.
-
- For a guest of type "kvm", the default ``video`` is: ``type`` with value
- "cirrus", ``vram`` with value "16384" and ``heads`` with value "1". By
- default, the first video device in domain xml is the primary one, but the
- optional attribute ``primary`` ( :since:`since 1.0.2` ) with value 'yes' can
- be used to mark the primary in cases of multiple video device. The
- non-primary must be type of "qxl" or ( :since:`since 2.4.0` ) "virtio".
-
-``model``
- The ``model`` element has a mandatory ``type`` attribute which takes the
- value "vga", "cirrus", "vmvga", "xen", "vbox", "qxl" ( :since:`since 0.8.6`
- ), "virtio" ( :since:`since 1.3.0` ), "gop" ( :since:`since 3.2.0` ), "bochs"
- ( :since:`since 5.6.0` ), "ramfb" ( :since:`since 5.9.0` ), or "none" (
- :since:`since 4.6.0` , depending on the hypervisor features available. The
- purpose of the type ``none`` is to instruct libvirt not to add a default
- video device in the guest (see the paragraph above). This legacy behaviour
- can be inconvenient in cases where GPU mediated devices are meant to be the
- only rendering device within a guest and so specifying another ``video``
- device along with type ``none``. Refer to Host device assignment to see how
- to add a mediated device into a guest.
-
- You can provide the amount of video memory in kibibytes (blocks of 1024
- bytes) using ``vram``. This is supported only for guest type of "vz", "qemu",
- "vbox", "vmx" and "xen". If no value is provided the default is used. If the
- size is not a power of two it will be rounded to closest one.
-
- The number of screen can be set using ``heads``. This is supported only for
- guests type of "vz", "kvm", "vbox" and "vmx".
-
- For guest type of "kvm" or "qemu" and model type "qxl" there are optional
- attributes. Attribute ``ram`` ( :since:` since 1.0.2` ) specifies the size of
- the primary bar, while the attribute ``vram`` specifies the secondary bar
- size. If ``ram`` or ``vram`` are not supplied a default value is used. The
- ``ram`` should also be rounded to power of two as ``vram``. There is also
- optional attribute ``vgamem`` ( :since:`since 1.2.11` ) to set the size of
- VGA framebuffer for fallback mode of QXL device. Attribute ``vram64`` (
- :since:`since 1.3.3` ) extends secondary bar and makes it addressable as
- 64bit memory.
-
- :since:`Since 5.9.0` , the ``model`` element may also have an optional
- ``resolution`` sub-element. The ``resolution`` element has attributes ``x``
- and ``y`` to set the minimum resolution for the video device. This
- sub-element is valid for model types "vga", "qxl", "bochs", and "virtio".
-
-``acceleration``
- Configure if video acceleration should be enabled.
-
- ``accel2d``
- Enable 2D acceleration (for vbox driver only, :since:`since 0.7.1` )
- ``accel3d``
- Enable 3D acceleration (for vbox driver :since:`since 0.7.1` , qemu driver
- :since:`since 1.3.0` )
- ``rendernode``
- Absolute path to a host's DRI device to be used for rendering (for
- 'vhostuser' driver only, :since:`since 5.8.0` ). If none is specified,
- libvirt will pick one available.
-
-``address``
- The optional ``address`` sub-element can be used to tie the video device to a
- particular PCI slot. On S390, ``address`` can be used to provide the CCW
- address for the video device ( :since:` since 4.2.0` ).
-``driver``
- The subelement ``driver`` can be used to tune the device:
-
- ``name``
- Specify the backend driver to use, either "qemu" or "vhostuser" depending
- on the hypervisor features available ( :since:`since 5.8.0` ). "qemu" is
- the default QEMU backend. "vhostuser" will use a separate vhost-user
- process backend (for ``virtio`` device).
- virtio options
- `Virtio-specific options <#elementsVirtio>`__ can also be set (
- :since:`Since 3.5.0` )
- VGA configuration
- Control how the video devices exposed to the guest using the ``vgaconf``
- attribute which takes the value "io", "on" or "off". At present, it's only
- applicable to the bhyve's "gop" video model type ( :since:`Since 3.5.0` )
+.. include:: formatdomain-devices-video.rst
:anchor:`<a id="elementsConsole"/>`
diff --git a/docs/meson.build b/docs/meson.build
index f26754852d..56791e3258 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -137,6 +137,7 @@ docs_rst_files = [
'formatdomain-devices-input.rst',
'formatdomain-devices-hub.rst',
'formatdomain-devices-graphics.rst',
+ 'formatdomain-devices-video.rst',
]
},
{ 'name': 'hacking' },
--
2.26.2
More information about the libvir-list
mailing list