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

[Xiang Zheng <zhengxiang9@huawei.com>]

On 2019/10/15 23:08, Peter Maydell wrote:
> On Tue, 15 Oct 2019 at 15:02, Xiang Zheng <zhengxiang9@huawei.com> wrote:
>>
>> From: Dongjiu Geng <gengdongjiu@huawei.com>
>>
>> Add APEI/GHES detailed design document
>>
>> Signed-off-by: Dongjiu Geng <gengdongjiu@huawei.com>
>> Signed-off-by: Xiang Zheng <zhengxiang9@huawei.com>
>> ---
>>  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.
> 

OK.

> 
>> +(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, I will fix them.


-- 

Thanks,
Xiang