| Message ID | 20230927151205.70930-8-peter.maydell@linaro.org |
|---|---|
| State | Accepted |
| Headers | show |
| Series | docs/specs: Convert txt files to rST | expand |
On 27/9/23 17:12, Peter Maydell wrote: > Convert docs/specs/vmcoreinfo.txt to rST format. > > Signed-off-by: Peter Maydell <peter.maydell@linaro.org> > --- > MAINTAINERS | 1 + > docs/specs/index.rst | 1 + > docs/specs/{vmcoreinfo.txt => vmcoreinfo.rst} | 33 ++++++++++--------- > 3 files changed, 19 insertions(+), 16 deletions(-) > rename docs/specs/{vmcoreinfo.txt => vmcoreinfo.rst} (50%) > > diff --git a/MAINTAINERS b/MAINTAINERS > index 9e27cad11c3..23ee617acaf 100644 > --- a/MAINTAINERS > +++ b/MAINTAINERS > @@ -2805,6 +2805,7 @@ F: include/sysemu/dump.h > F: qapi/dump.json > F: scripts/dump-guest-memory.py > F: stubs/dump.c > +F: docs/specs/vmcoreinfo.rst Good :) Cc'ing Marc-André. > Error reporting > M: Markus Armbruster <armbru@redhat.com> > diff --git a/docs/specs/index.rst b/docs/specs/index.rst > index 8d30968650b..7a56ccb2155 100644 > --- a/docs/specs/index.rst > +++ b/docs/specs/index.rst > @@ -30,3 +30,4 @@ guest hardware that is specific to QEMU. > pvpanic > standard-vga > virt-ctlr > + vmcoreinfo > diff --git a/docs/specs/vmcoreinfo.txt b/docs/specs/vmcoreinfo.rst > similarity index 50% > rename from docs/specs/vmcoreinfo.txt > rename to docs/specs/vmcoreinfo.rst > index bcbca6fe47c..462b04474d3 100644 > --- a/docs/specs/vmcoreinfo.txt > +++ b/docs/specs/vmcoreinfo.rst > @@ -2,19 +2,19 @@ > VMCoreInfo device > ================= > > -The `-device vmcoreinfo` will create a fw_cfg entry for a guest to > +The ``-device vmcoreinfo`` will create a ``fw_cfg`` entry for a guest to > store dump details. > > -etc/vmcoreinfo > -************** > +``etc/vmcoreinfo`` > +================== > > -A guest may use this fw_cfg entry to add information details to qemu > +A guest may use this ``fw_cfg`` entry to add information details to qemu > dumps. > > The entry of 16 bytes has the following layout, in little-endian:: > > -#define VMCOREINFO_FORMAT_NONE 0x0 > -#define VMCOREINFO_FORMAT_ELF 0x1 > + #define VMCOREINFO_FORMAT_NONE 0x0 > + #define VMCOREINFO_FORMAT_ELF 0x1 > > struct FWCfgVMCoreInfo { > uint16_t host_format; /* formats host supports */ > @@ -26,17 +26,17 @@ The entry of 16 bytes has the following layout, in little-endian:: > Only full write (of 16 bytes) are considered valid for further > processing of entry values. > > -A write of 0 in guest_format will disable further processing of > +A write of 0 in ``guest_format`` will disable further processing of > vmcoreinfo entry values & content. > > -You may write a guest_format that is not supported by the host, in > +You may write a ``guest_format`` that is not supported by the host, in > which case the entry data can be ignored by qemu (but you may still > -access it through a debugger, via vmcoreinfo_realize::vmcoreinfo_state). > +access it through a debugger, via ``vmcoreinfo_realize::vmcoreinfo_state``). > > Format & content > -**************** > +================ > > -As of qemu 2.11, only VMCOREINFO_FORMAT_ELF is supported. > +As of qemu 2.11, only ``VMCOREINFO_FORMAT_ELF`` is supported. Maybe s/qemu/QEMU/, otherwise: Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org> > The entry gives location and size of an ELF note that is appended in > qemu dumps. > @@ -44,10 +44,11 @@ qemu dumps. > The note format/class must be of the target bitness and the size must > be less than 1Mb. > > -If the ELF note name is "VMCOREINFO", it is expected to be the Linux > -vmcoreinfo note (see Documentation/ABI/testing/sysfs-kernel-vmcoreinfo > -in Linux source). In this case, qemu dump code will read the content > -as a key=value text file, looking for "NUMBER(phys_base)" key > +If the ELF note name is ``VMCOREINFO``, it is expected to be the Linux > +vmcoreinfo note (see `the kernel documentation for its format > +<https://www.kernel.org/doc/Documentation/ABI/testing/sysfs-kernel-vmcoreinfo>`_). > +In this case, qemu dump code will read the content > +as a key=value text file, looking for ``NUMBER(phys_base)`` key > value. The value is expected to be more accurate than architecture > guess of the value. This is useful for KASLR-enabled guest with > -ancient tools not handling the VMCOREINFO note. > +ancient tools not handling the ``VMCOREINFO`` note.
On Tue, Oct 31, 2023 at 7:43 PM Philippe Mathieu-Daudé <philmd@linaro.org> wrote: > > On 27/9/23 17:12, Peter Maydell wrote: > > Convert docs/specs/vmcoreinfo.txt to rST format. > > > > Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Acked-by: Marc-André Lureau <marcandre.lureau@redhat.com> > > --- > > MAINTAINERS | 1 + > > docs/specs/index.rst | 1 + > > docs/specs/{vmcoreinfo.txt => vmcoreinfo.rst} | 33 ++++++++++--------- > > 3 files changed, 19 insertions(+), 16 deletions(-) > > rename docs/specs/{vmcoreinfo.txt => vmcoreinfo.rst} (50%) > > > > diff --git a/MAINTAINERS b/MAINTAINERS > > index 9e27cad11c3..23ee617acaf 100644 > > --- a/MAINTAINERS > > +++ b/MAINTAINERS > > @@ -2805,6 +2805,7 @@ F: include/sysemu/dump.h > > F: qapi/dump.json > > F: scripts/dump-guest-memory.py > > F: stubs/dump.c > > +F: docs/specs/vmcoreinfo.rst > > Good :) > > Cc'ing Marc-André. > > > Error reporting > > M: Markus Armbruster <armbru@redhat.com> > > diff --git a/docs/specs/index.rst b/docs/specs/index.rst > > index 8d30968650b..7a56ccb2155 100644 > > --- a/docs/specs/index.rst > > +++ b/docs/specs/index.rst > > @@ -30,3 +30,4 @@ guest hardware that is specific to QEMU. > > pvpanic > > standard-vga > > virt-ctlr > > + vmcoreinfo > > diff --git a/docs/specs/vmcoreinfo.txt b/docs/specs/vmcoreinfo.rst > > similarity index 50% > > rename from docs/specs/vmcoreinfo.txt > > rename to docs/specs/vmcoreinfo.rst > > index bcbca6fe47c..462b04474d3 100644 > > --- a/docs/specs/vmcoreinfo.txt > > +++ b/docs/specs/vmcoreinfo.rst > > @@ -2,19 +2,19 @@ > > VMCoreInfo device > > ================= > > > > -The `-device vmcoreinfo` will create a fw_cfg entry for a guest to > > +The ``-device vmcoreinfo`` will create a ``fw_cfg`` entry for a guest to > > store dump details. > > > > -etc/vmcoreinfo > > -************** > > +``etc/vmcoreinfo`` > > +================== > > > > -A guest may use this fw_cfg entry to add information details to qemu > > +A guest may use this ``fw_cfg`` entry to add information details to qemu > > dumps. > > > > The entry of 16 bytes has the following layout, in little-endian:: > > > > -#define VMCOREINFO_FORMAT_NONE 0x0 > > -#define VMCOREINFO_FORMAT_ELF 0x1 > > + #define VMCOREINFO_FORMAT_NONE 0x0 > > + #define VMCOREINFO_FORMAT_ELF 0x1 > > > > struct FWCfgVMCoreInfo { > > uint16_t host_format; /* formats host supports */ > > @@ -26,17 +26,17 @@ The entry of 16 bytes has the following layout, in little-endian:: > > Only full write (of 16 bytes) are considered valid for further > > processing of entry values. > > > > -A write of 0 in guest_format will disable further processing of > > +A write of 0 in ``guest_format`` will disable further processing of > > vmcoreinfo entry values & content. > > > > -You may write a guest_format that is not supported by the host, in > > +You may write a ``guest_format`` that is not supported by the host, in > > which case the entry data can be ignored by qemu (but you may still > > -access it through a debugger, via vmcoreinfo_realize::vmcoreinfo_state). > > +access it through a debugger, via ``vmcoreinfo_realize::vmcoreinfo_state``). > > > > Format & content > > -**************** > > +================ > > > > -As of qemu 2.11, only VMCOREINFO_FORMAT_ELF is supported. > > +As of qemu 2.11, only ``VMCOREINFO_FORMAT_ELF`` is supported. > > Maybe s/qemu/QEMU/, otherwise: > > Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org> > > > The entry gives location and size of an ELF note that is appended in > > qemu dumps. > > @@ -44,10 +44,11 @@ qemu dumps. > > The note format/class must be of the target bitness and the size must > > be less than 1Mb. > > > > -If the ELF note name is "VMCOREINFO", it is expected to be the Linux > > -vmcoreinfo note (see Documentation/ABI/testing/sysfs-kernel-vmcoreinfo > > -in Linux source). In this case, qemu dump code will read the content > > -as a key=value text file, looking for "NUMBER(phys_base)" key > > +If the ELF note name is ``VMCOREINFO``, it is expected to be the Linux > > +vmcoreinfo note (see `the kernel documentation for its format > > +<https://www.kernel.org/doc/Documentation/ABI/testing/sysfs-kernel-vmcoreinfo>`_). > > +In this case, qemu dump code will read the content > > +as a key=value text file, looking for ``NUMBER(phys_base)`` key > > value. The value is expected to be more accurate than architecture > > guess of the value. This is useful for KASLR-enabled guest with > > -ancient tools not handling the VMCOREINFO note. > > +ancient tools not handling the ``VMCOREINFO`` note. >
diff --git a/MAINTAINERS b/MAINTAINERS index 9e27cad11c3..23ee617acaf 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -2805,6 +2805,7 @@ F: include/sysemu/dump.h F: qapi/dump.json F: scripts/dump-guest-memory.py F: stubs/dump.c +F: docs/specs/vmcoreinfo.rst Error reporting M: Markus Armbruster <armbru@redhat.com> diff --git a/docs/specs/index.rst b/docs/specs/index.rst index 8d30968650b..7a56ccb2155 100644 --- a/docs/specs/index.rst +++ b/docs/specs/index.rst @@ -30,3 +30,4 @@ guest hardware that is specific to QEMU. pvpanic standard-vga virt-ctlr + vmcoreinfo diff --git a/docs/specs/vmcoreinfo.txt b/docs/specs/vmcoreinfo.rst similarity index 50% rename from docs/specs/vmcoreinfo.txt rename to docs/specs/vmcoreinfo.rst index bcbca6fe47c..462b04474d3 100644 --- a/docs/specs/vmcoreinfo.txt +++ b/docs/specs/vmcoreinfo.rst @@ -2,19 +2,19 @@ VMCoreInfo device ================= -The `-device vmcoreinfo` will create a fw_cfg entry for a guest to +The ``-device vmcoreinfo`` will create a ``fw_cfg`` entry for a guest to store dump details. -etc/vmcoreinfo -************** +``etc/vmcoreinfo`` +================== -A guest may use this fw_cfg entry to add information details to qemu +A guest may use this ``fw_cfg`` entry to add information details to qemu dumps. The entry of 16 bytes has the following layout, in little-endian:: -#define VMCOREINFO_FORMAT_NONE 0x0 -#define VMCOREINFO_FORMAT_ELF 0x1 + #define VMCOREINFO_FORMAT_NONE 0x0 + #define VMCOREINFO_FORMAT_ELF 0x1 struct FWCfgVMCoreInfo { uint16_t host_format; /* formats host supports */ @@ -26,17 +26,17 @@ The entry of 16 bytes has the following layout, in little-endian:: Only full write (of 16 bytes) are considered valid for further processing of entry values. -A write of 0 in guest_format will disable further processing of +A write of 0 in ``guest_format`` will disable further processing of vmcoreinfo entry values & content. -You may write a guest_format that is not supported by the host, in +You may write a ``guest_format`` that is not supported by the host, in which case the entry data can be ignored by qemu (but you may still -access it through a debugger, via vmcoreinfo_realize::vmcoreinfo_state). +access it through a debugger, via ``vmcoreinfo_realize::vmcoreinfo_state``). Format & content -**************** +================ -As of qemu 2.11, only VMCOREINFO_FORMAT_ELF is supported. +As of qemu 2.11, only ``VMCOREINFO_FORMAT_ELF`` is supported. The entry gives location and size of an ELF note that is appended in qemu dumps. @@ -44,10 +44,11 @@ qemu dumps. The note format/class must be of the target bitness and the size must be less than 1Mb. -If the ELF note name is "VMCOREINFO", it is expected to be the Linux -vmcoreinfo note (see Documentation/ABI/testing/sysfs-kernel-vmcoreinfo -in Linux source). In this case, qemu dump code will read the content -as a key=value text file, looking for "NUMBER(phys_base)" key +If the ELF note name is ``VMCOREINFO``, it is expected to be the Linux +vmcoreinfo note (see `the kernel documentation for its format +<https://www.kernel.org/doc/Documentation/ABI/testing/sysfs-kernel-vmcoreinfo>`_). +In this case, qemu dump code will read the content +as a key=value text file, looking for ``NUMBER(phys_base)`` key value. The value is expected to be more accurate than architecture guess of the value. This is useful for KASLR-enabled guest with -ancient tools not handling the VMCOREINFO note. +ancient tools not handling the ``VMCOREINFO`` note.
Convert docs/specs/vmcoreinfo.txt to rST format. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> --- MAINTAINERS | 1 + docs/specs/index.rst | 1 + docs/specs/{vmcoreinfo.txt => vmcoreinfo.rst} | 33 ++++++++++--------- 3 files changed, 19 insertions(+), 16 deletions(-) rename docs/specs/{vmcoreinfo.txt => vmcoreinfo.rst} (50%)