[PATCH 29/32] docs: formatdomain-devices: Split out <shmem>

Signed-off-by: Peter Krempa <pkrempa(a)redhat.com&gt; --- docs/formatdomain-devices-shmem.rst | 50 ++++++++++++++++++++++++++++ docs/formatdomain-devices.rst | 51 +---------------------------- docs/meson.build | 1 + 3 files changed, 52 insertions(+), 50 deletions(-) create mode 100644 docs/formatdomain-devices-shmem.rst diff --git a/docs/formatdomain-devices-shmem.rst b/docs/formatdomain-devices-shmem.rst new file mode 100644 index 0000000000..82b8bae85b --- /dev/null +++ b/docs/formatdomain-devices-shmem.rst @@ -0,0 +1,50 @@ +:anchor:`<a id="elementsShmem"/>` + +Shared memory device +~~~~~~~~~~~~~~~~~~~~ + +A shared memory device allows to share a memory region between different virtual +machines and the host. :since:`Since 1.2.10, QEMU and KVM only` + +:: + + ... + <devices> + <shmem name='my_shmem0'> + <model type='ivshmem-plain'/> + <size unit='M'>4</size> + </shmem> + <shmem name='shmem_server'> + <model type='ivshmem-doorbell'/> + <size unit='M'>2</size> + <server path='/tmp/socket-shmem'/> + <msi vectors='32' ioeventfd='on'/> + </shmem> + </devices> + ... + +``shmem`` + The ``shmem`` element has one mandatory attribute, ``name`` to identify the + shared memory. This attribute cannot be directory specific to ``.`` or ``..`` + as well as it cannot involve path separator ``/``. +``model`` + Attribute ``type`` of the optional element ``model`` specifies the model of + the underlying device providing the ``shmem`` device. The models currently + supported are ``ivshmem`` (supports both server and server-less shmem, but is + deprecated by newer QEMU in favour of the -plain and -doorbell variants), + ``ivshmem-plain`` (only for server-less shmem) and ``ivshmem-doorbell`` (only + for shmem with the server). +``size`` + The optional ``size`` element specifies the size of the shared memory. This + must be power of 2 and greater than or equal to 1 MiB. +``server`` + The optional ``server`` element can be used to configure a server socket the + device is supposed to connect to. The optional ``path`` attribute specifies + the absolute path to the unix socket and defaults to + ``/var/lib/libvirt/shmem/$shmem-$name-sock``. +``msi`` + The optional ``msi`` element enables/disables (values "on"/"off", + respectively) MSI interrupts. This option can currently be used only together + with the ``server`` element. The ``vectors`` attribute can be used to specify + the number of interrupt vectors. The ``ioeventd`` attribute enables/disables + (values "on"/"off", respectively) ioeventfd. diff --git a/docs/formatdomain-devices.rst b/docs/formatdomain-devices.rst index b629f128bc..8b81662442 100644 --- a/docs/formatdomain-devices.rst +++ b/docs/formatdomain-devices.rst @@ -61,57 +61,8 @@ following characters: ``[a-zA-Z0-9_-]``. :since:`Since 3.9.0` .. include:: formatdomain-devices-tpm.rst .. include:: formatdomain-devices-nvram.rst .. include:: formatdomain-devices-panic.rst +.. include:: formatdomain-devices-shmem.rst -:anchor:`<a id="elementsShmem"/>` - -Shared memory device -~~~~~~~~~~~~~~~~~~~~ - -A shared memory device allows to share a memory region between different virtual -machines and the host. :since:`Since 1.2.10, QEMU and KVM only` - -:: - - ... - <devices> - <shmem name='my_shmem0'> - <model type='ivshmem-plain'/> - <size unit='M'>4</size> - </shmem> - <shmem name='shmem_server'> - <model type='ivshmem-doorbell'/> - <size unit='M'>2</size> - <server path='/tmp/socket-shmem'/> - <msi vectors='32' ioeventfd='on'/> - </shmem> - </devices> - ... - -``shmem`` - The ``shmem`` element has one mandatory attribute, ``name`` to identify the - shared memory. This attribute cannot be directory specific to ``.`` or ``..`` - as well as it cannot involve path separator ``/``. -``model`` - Attribute ``type`` of the optional element ``model`` specifies the model of - the underlying device providing the ``shmem`` device. The models currently - supported are ``ivshmem`` (supports both server and server-less shmem, but is - deprecated by newer QEMU in favour of the -plain and -doorbell variants), - ``ivshmem-plain`` (only for server-less shmem) and ``ivshmem-doorbell`` (only - for shmem with the server). -``size`` - The optional ``size`` element specifies the size of the shared memory. This - must be power of 2 and greater than or equal to 1 MiB. -``server`` - The optional ``server`` element can be used to configure a server socket the - device is supposed to connect to. The optional ``path`` attribute specifies - the absolute path to the unix socket and defaults to - ``/var/lib/libvirt/shmem/$shmem-$name-sock``. -``msi`` - The optional ``msi`` element enables/disables (values "on"/"off", - respectively) MSI interrupts. This option can currently be used only together - with the ``server`` element. The ``vectors`` attribute can be used to specify - the number of interrupt vectors. The ``ioeventd`` attribute enables/disables - (values "on"/"off", respectively) ioeventfd. :anchor:`<a id="elementsMemory"/>` diff --git a/docs/meson.build b/docs/meson.build index e8373ff2c7..c0437aea62 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -146,6 +146,7 @@ docs_rst_files = [ 'formatdomain-devices-tpm.rst', 'formatdomain-devices-nvram.rst', 'formatdomain-devices-panic.rst', + 'formatdomain-devices-shmem.rst', ] }, { 'name': 'hacking' }, -- 2.26.2