[PATCH] docs/vm: hwpoison.rst: Fix quote formatting

[PATCH] docs/vm: hwpoison.rst: Fix quote formatting

[Valentin Schneider]

The asterisks prepended to the quoted text currently get translated to
bullet points, which gets increasingly confusing the smaller your
screen is (when viewing the sphinx output, that is).

Convert the whole quote to a literal block.

Signed-off-by: Valentin Schneider <valentin.schneider@arm.com>
---
 Documentation/vm/hwpoison.rst | 52 +++++++++++++++++------------------
 1 file changed, 26 insertions(+), 26 deletions(-)

diff --git a/Documentation/vm/hwpoison.rst b/Documentation/vm/hwpoison.rst
index 09bd24a92784..a5c884293dac 100644
--- a/Documentation/vm/hwpoison.rst
+++ b/Documentation/vm/hwpoison.rst
@@ -13,32 +13,32 @@ kill the processes associated with it and avoid using it in the future.
 
 This patchkit implements the necessary infrastructure in the VM.
 
-To quote the overview comment:
-
- * High level machine check handler. Handles pages reported by the
- * hardware as being corrupted usually due to a 2bit ECC memory or cache
- * failure.
- *
- * This focusses on pages detected as corrupted in the background.
- * When the current CPU tries to consume corruption the currently
- * running process can just be killed directly instead. This implies
- * that if the error cannot be handled for some reason it's safe to
- * just ignore it because no corruption has been consumed yet. Instead
- * when that happens another machine check will happen.
- *
- * Handles page cache pages in various states. The tricky part
- * here is that we can access any page asynchronous to other VM
- * users, because memory failures could happen anytime and anywhere,
- * possibly violating some of their assumptions. This is why this code
- * has to be extremely careful. Generally it tries to use normal locking
- * rules, as in get the standard locks, even if that means the
- * error handling takes potentially a long time.
- *
- * Some of the operations here are somewhat inefficient and have non
- * linear algorithmic complexity, because the data structures have not
- * been optimized for this case. This is in particular the case
- * for the mapping from a vma to a process. Since this case is expected
- * to be rare we hope we can get away with this.
+To quote the overview comment::
+
+	High level machine check handler. Handles pages reported by the
+	hardware as being corrupted usually due to a 2bit ECC memory or cache
+	failure.
+
+	This focusses on pages detected as corrupted in the background.
+	When the current CPU tries to consume corruption the currently
+	running process can just be killed directly instead. This implies
+	that if the error cannot be handled for some reason it's safe to
+	just ignore it because no corruption has been consumed yet. Instead
+	when that happens another machine check will happen.
+
+	Handles page cache pages in various states. The tricky part
+	here is that we can access any page asynchronous to other VM
+	users, because memory failures could happen anytime and anywhere,
+	possibly violating some of their assumptions. This is why this code
+	has to be extremely careful. Generally it tries to use normal locking
+	rules, as in get the standard locks, even if that means the
+	error handling takes potentially a long time.
+
+	Some of the operations here are somewhat inefficient and have non
+	linear algorithmic complexity, because the data structures have not
+	been optimized for this case. This is in particular the case
+	for the mapping from a vma to a process. Since this case is expected
+	to be rare we hope we can get away with this.
 
 The code consists of a the high level handler in mm/memory-failure.c,
 a new page poison bit and various checks in the VM to handle poisoned
-- 
2.20.1

Re: [PATCH] docs/vm: hwpoison.rst: Fix quote formatting

[Jonathan Corbet]

On Tue, 18 Jun 2019 15:56:05 +0100
Valentin Schneider <valentin.schneider@arm.com> wrote:

> The asterisks prepended to the quoted text currently get translated to
> bullet points, which gets increasingly confusing the smaller your
> screen is (when viewing the sphinx output, that is).
> 
> Convert the whole quote to a literal block.
> 
> Signed-off-by: Valentin Schneider <valentin.schneider@arm.com>

That definitely seems worth fixing, and I can apply this.  But a few
things to ponder first...

 - If you convert it to a literal block, the asterisks can remain, making
   for a less intrusive patch.

 - I was wondering if we should just use a kernel-doc directive to pull
   the comment directly from the source, but investigation quickly showed
   that the "overview comment" doesn't actually exist in anything close to
   the quoted form.  See mm/memory-failure.c.

Given that, and things like references to support in "upcoming Intel
CPUs", I suspect that this document is pretty seriously out of date and
needs some more in-depth attention.  If you're playing in this area and
feel like it, updating the document for real would be much appreciated...:)

Thanks,

jon

Re: [PATCH] docs/vm: hwpoison.rst: Fix quote formatting

[Valentin Schneider]

On 18/06/2019 16:31, Jonathan Corbet wrote:
> On Tue, 18 Jun 2019 15:56:05 +0100
> Valentin Schneider <valentin.schneider@arm.com> wrote:
> 
>> The asterisks prepended to the quoted text currently get translated to
>> bullet points, which gets increasingly confusing the smaller your
>> screen is (when viewing the sphinx output, that is).
>>
>> Convert the whole quote to a literal block.
>>
>> Signed-off-by: Valentin Schneider <valentin.schneider@arm.com>
> 
> That definitely seems worth fixing, and I can apply this.  But a few
> things to ponder first...
> 
>  - If you convert it to a literal block, the asterisks can remain, making
>    for a less intrusive patch.
> 
>  - I was wondering if we should just use a kernel-doc directive to pull
>    the comment directly from the source, but investigation quickly showed
>    that the "overview comment" doesn't actually exist in anything close to
>    the quoted form.  See mm/memory-failure.c.
> 
> Given that, and things like references to support in "upcoming Intel
> CPUs", I suspect that this document is pretty seriously out of date and
> needs some more in-depth attention.  If you're playing in this area and
> feel like it, updating the document for real would be much appreciated...:)
> 

I'm afraid this was only a "drive-by" patch, as I just happened to skim
through this page on my phone while waiting for a meeting - I'm quite
clueless about page poisoning.

However, I could try to replace the quote with a kernel-doc directive to
get a more up-to-date description (and maybe add a small note to say the
rest of the doc is somewhat outdated). That, or just keep the quote as is
but keep the asterisks - whichever you're happier with.

> Thanks,
> 
> jon
> 

Re: [PATCH] docs/vm: hwpoison.rst: Fix quote formatting

[Jonathan Corbet]

On Tue, 18 Jun 2019 16:51:06 +0100
Valentin Schneider <valentin.schneider@arm.com> wrote:

> I'm afraid this was only a "drive-by" patch, as I just happened to skim
> through this page on my phone while waiting for a meeting - I'm quite
> clueless about page poisoning.

No worries.  Thanks for the patch; it makes things better than they were
before, and I can't complain about that!

jon