[PATCH 20/32] docs: formatdomain-devices: Split out <videO>

Signed-off-by: Peter Krempa <pkrempa(a)redhat.com&gt; --- 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