[PATCH] docs: formatdomain: Convert to rst
Ján Tomko
jtomko at redhat.com
Tue Aug 4 08:51:23 UTC 2020
On a Monday in 2020, Peter Krempa wrote:
>For now just plain conversion to rst. Anchors which existed until now
>are preserved, but the table of contents now uses the docutils-generated
>ones.
>
>Additionally <code> which was nested in a link (<a>) was removed as rst
>doesn't support nesting of inline markup.
>
>The only anchor which wasn't restored is
>'elementsDiskBackingStoreIndex' and it's only reference was removed.
s/it's/its/
(Should we also convert the documentation from English to a saner
language?)
>
>Signed-off-by: Peter Krempa <pkrempa at redhat.com>
>---
>
>A rebased version of this patch. For now anchors and links are kept
>as-is as there wasn't a consensus on how to approach it.
>
>This file is a magnet for conflicts so it's broken often and thus
>splitting it up will be made later once I will not get rippling
>conflicts.
>
>The idea to split up into sections (if we decide to do so) can be done
>incrementally. As a first step the hacky HTML anchors will be removed
>and links will be fixed and then we can split up everyting, but that's
>for later.
If it's any consultation, I found links using the anchors in the
virt-install man page.
Also note that while you kept the old anchors (I haven't checked),
you're introducing new ones here that are accessible both via
the ToC and that little hidden link we have on each headline.
From the visual point of view, the bullet and definition list
are spacier in the rst version. But that's out of scope of this patch.
>
>For now I've updated the file manually from the last posting, but you
>can look how I did the automatic part at:
>
>https://gitlab.com/pipo.sk/libvirt/-/commit/3d7e23948564502ff01160a73abd3973360764d2
>
> docs/formatdomain.html.in | 9860 -------------------------------------
> docs/formatdomain.rst | 7453 ++++++++++++++++++++++++++++
> docs/meson.build | 2 +-
> 3 files changed, 7454 insertions(+), 9861 deletions(-)
> delete mode 100644 docs/formatdomain.html.in
> create mode 100644 docs/formatdomain.rst
>
>diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
>new file mode 100644
>index 0000000000..a9c4f46843
>--- /dev/null
>+++ b/docs/formatdomain.rst
[...]
>+``smbios``
>+ How to populate SMBIOS information visible in the guest. The ``mode``
>+ attribute must be specified, and is either "emulate" (let the hypervisor
>+ generate all values), "host" (copy all of Block 0 and Block 1, except for the
>+ UUID, from the host's SMBIOS values; the
>+ `virConnectGetSysinfo <html/libvirt-libvirt-host.html#virConnectGetSysinfo>`__
>+ call can be used to see what values are copied), or "sysinfo" (use the values
>+ in the `sysinfo <#elementsSysinfo>`__ element). If not specified, the
>+ hypervisor default is used. :since:` Since 0.8.7`
The space before 'Since' keeps this from being interpreted properly.
>+
>+Up till here the BIOS/UEFI configuration knobs are generic enough to be
>+implemented by majority (if not all) firmwares out there. However, from now on
>+not every single setting makes sense to all firmwares. For instance,
>+``rebootTimeout`` doesn't make sense for UEFI, ``useserial`` might not be usable
>+with a BIOS firmware that doesn't produce any output onto serial line, etc.
>+Moreover, firmwares don't usually export their capabilities for libvirt (or
>+users) to check. And the set of their capabilities can change with every new
>+release. Hence users are advised to try the settings they use before relying on
>+them in production.
>+
>+``bootmenu``
>+ Whether or not to enable an interactive boot menu prompt on guest startup.
>+ The ``enable`` attribute can be either "yes" or "no". If not specified, the
>+ hypervisor default is used. :since:` Since 0.8.3` Additional attribute
Same here.
>+ ``timeout`` takes the number of milliseconds the boot menu should wait until
>+ it times out. Allowed values are numbers in range [0, 65535] inclusive and it
>+ is ignored unless ``enable`` is set to "yes". :since:`Since 1.2.8`
[...]
>+
>+``memory``
>+ The maximum allocation of memory for the guest at boot time. The memory
>+ allocation includes possible additional memory devices specified at start or
>+ hotplugged later. The units for this value are determined by the optional
>+ attribute ``unit``, which defaults to "KiB" (kibibytes, 2\ :sup:`10` or
>+ blocks of 1024 bytes). Valid units are "b" or "bytes" for bytes, "KB" for
>+ kilobytes (10:sup:`3` or 1,000 bytes), "k" or "KiB" for kibibytes (1024
>+ bytes), "MB" for megabytes (10:sup:`6` or 1,000,000 bytes), "M" or "MiB" for
>+ mebibytes (2:sup:`20` or 1,048,576 bytes), "GB" for gigabytes (10:sup:`9` or
>+ 1,000,000,000 bytes), "G" or "GiB" for gibibytes (2:sup:`30` or 1,073,741,824
>+ bytes), "TB" for terabytes (10:sup:`12` or 1,000,000,000,000 bytes), or "T"
>+ or "TiB" for tebibytes (2:sup:`40` or 1,099,511,627,776 bytes). However, the
>+ value will be rounded up to the nearest kibibyte by libvirt, and may be
>+ further rounded to the granularity supported by the hypervisor. Some
>+ hypervisors also enforce a minimum, such as 4000KiB. In case
>+ `NUMA <#elementsCPU>`__ is configured for the guest the ``memory`` element
>+ can be omitted. In the case of crash, optional attribute ``dumpCore`` can be
>+ used to control whether the guest memory should be included in the generated
>+ coredump or not (values "on", "off"). :since:```unit`` since 0.9.11` ,
>+ :since:```dumpCore`` since 0.10.2 (QEMU only)`
``unit`` :since:`since 0.9.11`, ``dumpCore`` :since:`since 0.10.2 (QEMU
only)`
>+``maxMemory``
>+ The run time maximum memory allocation of the guest. The initial memory
>+ specified by either the ``<memory>`` element or the NUMA cell size
>+ configuration can be increased by hot-plugging of memory to the limit
>+ specified by this element. The ``unit`` attribute behaves the same as for
>+ ``<memory>``. The ``slots`` attribute specifies the number of slots available
>+ for adding memory to the guest. The bounds are hypervisor specific. Note that
>+ due to alignment of the memory chunks added via memory hotplug the full size
>+ allocation specified by this element may be impossible to achieve.
>+ :since:`Since 1.2.14 supported by the QEMU driver.`
>+
[...]
>+``memtune``
>+ The optional ``memtune`` element provides details regarding the memory
>+ tunable parameters for the domain. If this is omitted, it defaults to the OS
>+ provided defaults. For QEMU/KVM, the parameters are applied to the QEMU
>+ process as a whole. Thus, when counting them, one needs to add up guest RAM,
>+ guest video RAM, and some memory overhead of QEMU itself. The last piece is
>+ hard to determine so one needs guess and try. For each tunable, it is
>+ possible to designate which unit the number is in on input, using the same
>+ values as for ``<memory>``. For backwards compatibility, output is always in
>+ KiB. :since:```unit`` since 0.9.11` Possible values for all \*_limit
``unit`` :since:`since 0.9.11`
>+ parameters are in range from 0 to VIR_DOMAIN_MEMORY_PARAM_UNLIMITED.
>+``hard_limit``
>+ The optional ``hard_limit`` element is the maximum memory the guest can use.
>+ The units for this value are kibibytes (i.e. blocks of 1024 bytes). Users of
>+ QEMU and KVM are strongly advised not to set this limit as domain may get
>+ killed by the kernel if the guess is too low, and determining the memory
>+ needed for a process to run is an `undecidable
>+ problem <http://en.wikipedia.org/wiki/Undecidable_problem>`__; that said, if
>+ you already set ``locked`` in `memory backing <#elementsMemoryBacking>`__
>+ because your workload demands it, you'll have to take into account the
>+ specifics of your deployment and figure out a value for ``hard_limit`` that
>+ is large enough to support the memory requirements of your guest, but small
>+ enough to protect your host against a malicious guest locking all memory.
[...]
>+``hyperv``
>+ Enable various features improving behavior of guests running Microsoft
>+ Windows.
>+
>+ =============== ====================================================================== ============================================ =======================================================
>+ Feature Description Value Since
>+ =============== ====================================================================== ============================================ =======================================================
>+ relaxed Relax constraints on timers on, off :since:`1.0.0 (QEMU 2.0)`
>+ vapic Enable virtual APIC on, off :since:`1.1.0 (QEMU 2.0)`
>+ spinlocks Enable spinlock support on, off; retries - at least 4095 :since:`1.1.0 (QEMU 2.0)`
>+ vpindex Virtual processor index on, off :since:`1.3.3 (QEMU 2.5)`
>+ runtime Processor time spent on running guest code and on behalf of guest code on, off :since:`1.3.3 (QEMU 2.5)`
>+ synic Enable Synthetic Interrupt Controller (SynIC) on, off :since:`1.3.3 (QEMU 2.6)`
>+ stimer Enable SynIC timers, optionally with Direct Mode support on, off; direct - on,off :since:`1.3.3 (QEMU 2.6), direct mode 5.7.0 (QEMU 4.1)`
>+ reset Enable hypervisor reset on, off :since:`1.3.3 (QEMU 2.5)`
>+ vendor_id Set hypervisor vendor id on, off; value - string, up to 12 characters :since:`1.3.3 (QEMU 2.5)`
>+ frequencies Expose frequency MSRs on, off :since:`4.7.0 (QEMU 2.12)`
>+ reenlightenment Enable re-enlightenment notification on migration on, off :since:`4.7.0 (QEMU 3.0)`
>+ tlbflush Enable PV TLB flush support on, off :since:`4.7.0 (QEMU 3.0)`
>+ ipi Enable PV IPI support on, off :since:`4.10.0 (QEMU 3.1)`
>+ evmcs Enable Enlightened VMCS on, off :since:`4.10.0 (QEMU 3.1)`
>+ =============== ====================================================================== ============================================ =======================================================
This one deserves a list-table eventually. Not a requirement for this
commit.
[...]
>+``target``
>+ The ``target`` element controls the bus / device under which the disk is
>+ exposed to the guest OS. The ``dev`` attribute indicates the "logical" device
>+ name. The actual device name specified is not guaranteed to map to the device
>+ name in the guest OS. Treat it as a device ordering hint. The optional
>+ ``bus`` attribute specifies the type of disk device to emulate; possible
>+ values are driver specific, with typical values being "ide", "scsi",
>+ "virtio", "xen", "usb", "sata", or "sd" :since:`"sd" since 1.1.2` . If
>+ omitted, the bus type is inferred from the style of the device name (e.g. a
>+ device named 'sda' will typically be exported using a SCSI bus). The optional
>+ attribute ``tray`` indicates the tray status of the removable disks (i.e.
>+ CDROM or Floppy disk), the value can be either "open" or "closed", defaults
>+ to "closed". NB, the value of ``tray`` could be updated while the domain is
>+ running. The optional attribute ``removable`` sets the removable flag for USB
>+ disks, and its value can be either "on" or "off", defaulting to "off".
>+ :since:`Since 0.0.3; ``bus`` attribute since 0.4.3; ``tray`` attribute since
>+ 0.9.11; "usb" attribute value since after 0.4.4; "sata" attribute value since
>+ 0.9.7; "removable" attribute value since 1.1.3`
:since:`Since 0.0.3`; ``bus`` attribute :since:`since 0.4.3`; ``tray`` attribute
:since:`since 0.9.11`; "usb" attribute value :since:`since after 0.4.4`;
"sata" attribute value :since: `since 0.9.7`; "removable" attribute value
:since:`since 1.1.3`
(I know half of those use different wordings and aren't in double
backticks, but that's what I consider a faithful conversion)
[...]
>+Virtual network
>+^^^^^^^^^^^^^^^
>+
>+**This is the recommended config for general guest connectivity on hosts with
>+dynamic / wireless networking configs (or multi-host environments where the host
>+hardware details are described separately in a ``<network>`` definition
>+:since:`Since 0.9.4` ).**
The 'since' only refers to the part in parentheses (added in
commit 07f4136993c3cce619ff92f4687171a335f6bf51 ) so I suggest only
bolding the first part of the sentence::
**This is the recommended config for general guest connectivity on hosts with
dynamic / wireless networking configs.** (or multi-host environments where the host
hardware details are described separately in a ``<network>`` definition
:since:`Since 0.9.4` ).
>+
>+Provides a connection whose details are described by the named network
>+definition. Depending on the virtual network's "forward mode" configuration, the
>+network may be totally isolated (no ``<forward>`` element given), NAT'ing to an
>+explicit network device or to the default route (``<forward mode='nat'>``),
>+routed with no NAT (``<forward mode='route'/>``), or connected directly to one
>+of the host's network interfaces (via macvtap) or bridge devices
>+((``<forward mode='bridge|private|vepa|passthrough'/>`` :since:`Since
>+0.9.4` )
[...]
>+Setting NIC driver-specific options
>+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>+
>+::
>+
>+ ...
>+ <devices>
>+ <interface type='network'>
>+ <source network='default'/>
>+ <target dev='vnet1'/>
>+ <model type='virtio'/>
>+ <driver name='vhost' txmode='iothread' ioeventfd='on' event_idx='off' queues='5' rx_queue_size='256' tx_queue_size='256'>
>+ <host csum='off' gso='off' tso4='off' tso6='off' ecn='off' ufo='off' mrg_rxbuf='off'/>
>+ <guest csum='off' tso4='off' tso6='off' ecn='off' ufo='off'/>
These were bold in the HTML version. Odd choice, given that most of
these have a bold warning to leave them alone unless you know what
you're doing.
>+ </driver>
>+ </interface>
>+ </devices>
>+ ...
>+
Reviewed-by: Ján Tomko <jtomko at redhat.com>
Jano
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 488 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20200804/2311f79a/attachment-0001.sig>
More information about the libvir-list
mailing list