Re: [PATCH v19 2/5] docs: APEI GHES generation and CPER record description

[Peter Maydell]

On Tue, 15 Oct 2019 at 15:02, Xiang Zheng <address@hidden> wrote:
>
> From: Dongjiu Geng <address@hidden>
>
> Add APEI/GHES detailed design document
>
> Signed-off-by: Dongjiu Geng <address@hidden>
> Signed-off-by: Xiang Zheng <address@hidden>
> ---
>  docs/specs/acpi_hest_ghes.rst | 94 
> +++++++++++++++++++++++++++++++++++++++++++
>  docs/specs/index.rst          |  1 +
>  2 files changed, 95 insertions(+)
>  create mode 100644 docs/specs/acpi_hest_ghes.rst
>
> diff --git a/docs/specs/acpi_hest_ghes.rst b/docs/specs/acpi_hest_ghes.rst
> new file mode 100644
> index 0000000..905b6d1
> --- /dev/null
> +++ b/docs/specs/acpi_hest_ghes.rst
> @@ -0,0 +1,94 @@
> +APEI tables generating and CPER record
> +======================================
> +
> +Copyright (c) 2019 HUAWEI TECHNOLOGIES CO., LTD.
> +
> +This work is licensed under the terms of the GNU GPL, version 2 or later.
> +See the COPYING file in the top-level directory.

This puts the copyright/license statement into the HTML rendered
docs seen by the user. We generally put them into an RST comment,
so they're in the source .rst but not the rendered views, like this:

diff --git a/docs/specs/acpi_hest_ghes.rst b/docs/specs/acpi_hest_ghes.rst
index 5b43e4b0da2..348825f9d3e 100644
--- a/docs/specs/acpi_hest_ghes.rst
+++ b/docs/specs/acpi_hest_ghes.rst
@@ -1,10 +1,11 @@
 APEI tables generating and CPER record
 ======================================

-Copyright (c) 2019 HUAWEI TECHNOLOGIES CO., LTD.
+..
+   Copyright (c) 2019 HUAWEI TECHNOLOGIES CO., LTD.

-This work is licensed under the terms of the GNU GPL, version 2 or later.
-See the COPYING file in the top-level directory.
+   This work is licensed under the terms of the GNU GPL, version 2 or later.
+   See the COPYING file in the top-level directory.


> +(9) When QEMU gets a SIGBUS from the kernel, QEMU formats the CPER right into
> +    guest memory, and then injects platform specific interrupt (in case of
> +    arm/virt machine it's Synchronous External Abort) as a notification which
> +    is necessary for notifying the guest.
> +
> +(10) This notification (in virtual hardware) will be handled by the guest
> +    kernel, guest APEI driver will read the CPER which is recorded by QEMU 
> and
> +    do the recovery.

Sphinx thinks the indentation here is not syntactically valid:

  SPHINX  docs/specs

Warning, treated as error:
/home/petmay01/linaro/qemu-from-laptop/qemu/docs/specs/acpi_hest_ghes.rst:93:Enumerated
list ends without a blank line; unexpected unindent.
Makefile:997: recipe for target 'docs/specs/index.html' failed

That's because for an enumerated list all the lines in the paragraph need to
start at the same column. Moving in the two following lines in the (10) item
fixes this:

--- a/docs/specs/acpi_hest_ghes.rst
+++ b/docs/specs/acpi_hest_ghes.rst
@@ -90,5 +90,5 @@ Design Details
     is necessary for notifying the guest.

 (10) This notification (in virtual hardware) will be handled by the guest
-    kernel, guest APEI driver will read the CPER which is recorded by QEMU and
-    do the recovery.
+     kernel, guest APEI driver will read the CPER which is recorded by QEMU and
+     do the recovery.

thanks
-- PMM