[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [for-5.2 4/9] docs/system/virtio-pmem.rst: Fix minor style issues
From: |
Pankaj Gupta |
Subject: |
Re: [for-5.2 4/9] docs/system/virtio-pmem.rst: Fix minor style issues |
Date: |
Thu, 19 Nov 2020 15:17:37 +0100 |
> The virtio-pmem documentation has some minor style issues we hadn't
> noticed since we weren't rendering it in our docs:
>
> * Sphinx doesn't complain about overlong title-underlining the
> way it complains about too-short underlining, but it looks odd;
> make the underlines of the top level title the right length
>
> * Indent of paragraphs makes them render as blockquotes;
> remove the indent so they just render as normal text
>
> * Leading 'o' isn't rst markup, so it just renders as a literal
> "o"; reformat as a subsection heading instead
>
> * "QEMU" in the document title and section headings are a bit
> odd and unnecessary since this is the QEMU manual; delete
> or rephrase them
>
> * There's no need to specify what QEMU version the device first
> appeared in.
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
> docs/system/virtio-pmem.rst | 55 ++++++++++++++++++-------------------
> 1 file changed, 27 insertions(+), 28 deletions(-)
>
> diff --git a/docs/system/virtio-pmem.rst b/docs/system/virtio-pmem.rst
> index 4bf5d004432..e5f91eff1c2 100644
> --- a/docs/system/virtio-pmem.rst
> +++ b/docs/system/virtio-pmem.rst
> @@ -1,38 +1,37 @@
>
> -========================
> -QEMU virtio pmem
> -========================
> +===========
> +virtio pmem
> +===========
>
> - This document explains the setup and usage of the virtio pmem device
> - which is available since QEMU v4.1.0.
> -
> - The virtio pmem device is a paravirtualized persistent memory device
> - on regular (i.e non-NVDIMM) storage.
> +This document explains the setup and usage of the virtio pmem device.
> +The virtio pmem device is a paravirtualized persistent memory device
> +on regular (i.e non-NVDIMM) storage.
>
> Usecase
> --------
>
> - Virtio pmem allows to bypass the guest page cache and directly use
> - host page cache. This reduces guest memory footprint as the host can
> - make efficient memory reclaim decisions under memory pressure.
> +Virtio pmem allows to bypass the guest page cache and directly use
> +host page cache. This reduces guest memory footprint as the host can
> +make efficient memory reclaim decisions under memory pressure.
>
> -o How does virtio-pmem compare to the nvdimm emulation supported by QEMU?
> +How does virtio-pmem compare to the nvdimm emulation?
> +-----------------------------------------------------
>
> - NVDIMM emulation on regular (i.e. non-NVDIMM) host storage does not
> - persist the guest writes as there are no defined semantics in the device
> - specification. The virtio pmem device provides guest write persistence
> - on non-NVDIMM host storage.
> +NVDIMM emulation on regular (i.e. non-NVDIMM) host storage does not
> +persist the guest writes as there are no defined semantics in the device
> +specification. The virtio pmem device provides guest write persistence
> +on non-NVDIMM host storage.
>
> virtio pmem usage
> -----------------
>
> - A virtio pmem device backed by a memory-backend-file can be created on
> - the QEMU command line as in the following example::
> +A virtio pmem device backed by a memory-backend-file can be created on
> +the QEMU command line as in the following example::
>
> -object
> memory-backend-file,id=mem1,share,mem-path=./virtio_pmem.img,size=4G
> -device virtio-pmem-pci,memdev=mem1,id=nv1
>
> - where:
> +where:
>
> - "object memory-backend-file,id=mem1,share,mem-path=<image>, size=<image
> size>"
> creates a backend file with the specified size.
> @@ -40,8 +39,8 @@ virtio pmem usage
> - "device virtio-pmem-pci,id=nvdimm1,memdev=mem1" creates a virtio pmem
> pci device whose storage is provided by above memory backend device.
>
> - Multiple virtio pmem devices can be created if multiple pairs of "-object"
> - and "-device" are provided.
> +Multiple virtio pmem devices can be created if multiple pairs of "-object"
> +and "-device" are provided.
>
> Hotplug
> -------
> @@ -59,14 +58,14 @@ the guest::
> Guest Data Persistence
> ----------------------
>
> - Guest data persistence on non-NVDIMM requires guest userspace applications
> - to perform fsync/msync. This is different from a real nvdimm backend where
> - no additional fsync/msync is required. This is to persist guest writes in
> - host backing file which otherwise remains in host page cache and there is
> - risk of losing the data in case of power failure.
> +Guest data persistence on non-NVDIMM requires guest userspace applications
> +to perform fsync/msync. This is different from a real nvdimm backend where
> +no additional fsync/msync is required. This is to persist guest writes in
> +host backing file which otherwise remains in host page cache and there is
> +risk of losing the data in case of power failure.
>
> - With virtio pmem device, MAP_SYNC mmap flag is not supported. This provides
> - a hint to application to perform fsync for write persistence.
> +With virtio pmem device, MAP_SYNC mmap flag is not supported. This provides
> +a hint to application to perform fsync for write persistence.
>
> Limitations
> ------------
Reviewed-by: Pankaj Gupta <pankaj.gupta@cloud.ionos.com>
- [for-5.2 0/9] docs: Move orphan top-level .rst files into manuals, Peter Maydell, 2020/11/12
- [for-5.2 1/9] docs: Move virtio-net-failover.rst into the system manual, Peter Maydell, 2020/11/12
- [for-5.2 2/9] docs: Move cpu-hotplug.rst into the system manual, Peter Maydell, 2020/11/12
- [for-5.2 3/9] docs: Move virtio-pmem.rst into the system manual, Peter Maydell, 2020/11/12
- [for-5.2 4/9] docs/system/virtio-pmem.rst: Fix minor style issues, Peter Maydell, 2020/11/12
- [for-5.2 5/9] docs: Split out 'pc' machine model docs into their own file, Peter Maydell, 2020/11/12
- [for-5.2 6/9] docs: Move microvm.rst into the system manual, Peter Maydell, 2020/11/12
- [for-5.2 7/9] docs: Move pr-manager.rst into the system manual, Peter Maydell, 2020/11/12
- [for-5.2 9/9] docs/system/pr-manager.rst: Fix minor docs nits, Peter Maydell, 2020/11/12
- [for-5.2 8/9] docs: Split qemu-pr-helper documentation into tools manual, Peter Maydell, 2020/11/12