[PATCH] Documentation: exception-tables.rst: Fix the wrong steps referenced

[PATCH] Documentation: exception-tables.rst: Fix the wrong steps referenced

[Li Zhijian]

When it was in text format, it correctly hardcoded steps 8a to 8c.
However, after it was converted to RST, the sequence numbers were
auto-generated during rendering and became incorrect after some
steps were inserted.

Change it to refer to steps a to c in a relative way.

Signed-off-by: Li Zhijian <lizhijian@fujitsu.com>
---
 Documentation/arch/x86/exception-tables.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/arch/x86/exception-tables.rst b/Documentation/arch/x86/exception-tables.rst
index efde1fef4fbd..562d1bc6d448 100644
--- a/Documentation/arch/x86/exception-tables.rst
+++ b/Documentation/arch/x86/exception-tables.rst
@@ -297,7 +297,7 @@ vma occurs?
    c) execution continues at local label 2 (address of the
       instruction immediately after the faulting user access).
 
-The steps 8a to 8c in a certain way emulate the faulting instruction.
+The steps a to c above in a certain way emulate the faulting instruction.
 
 That's it, mostly. If you look at our example, you might ask why
 we set EAX to -EFAULT in the exception handler code. Well, the
-- 
2.29.2

Re: [PATCH] Documentation: exception-tables.rst: Fix the wrong steps referenced

[Jonathan Corbet]

Li Zhijian <lizhijian@fujitsu.com> writes:

> When it was in text format, it correctly hardcoded steps 8a to 8c.
> However, after it was converted to RST, the sequence numbers were
> auto-generated during rendering and became incorrect after some
> steps were inserted.
>
> Change it to refer to steps a to c in a relative way.
>
> Signed-off-by: Li Zhijian <lizhijian@fujitsu.com>
> ---
>  Documentation/arch/x86/exception-tables.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/arch/x86/exception-tables.rst b/Documentation/arch/x86/exception-tables.rst
> index efde1fef4fbd..562d1bc6d448 100644
> --- a/Documentation/arch/x86/exception-tables.rst
> +++ b/Documentation/arch/x86/exception-tables.rst
> @@ -297,7 +297,7 @@ vma occurs?
>     c) execution continues at local label 2 (address of the
>        instruction immediately after the faulting user access).
>  
> -The steps 8a to 8c in a certain way emulate the faulting instruction.
> +The steps a to c above in a certain way emulate the faulting instruction.
>  

Those steps render as 1, 2, and 3 ... where did "a to c" come from?

Thanks,

jon

Re: [PATCH] Documentation: exception-tables.rst: Fix the wrong steps referenced

[Zhijian Li (Fujitsu)]

On 18/06/2024 06:43, Jonathan Corbet wrote:
> Li Zhijian <lizhijian@fujitsu.com> writes:
> 
>> When it was in text format, it correctly hardcoded steps 8a to 8c.
>> However, after it was converted to RST, the sequence numbers were
>> auto-generated during rendering and became incorrect after some
>> steps were inserted.
>>
>> Change it to refer to steps a to c in a relative way.
>>
>> Signed-off-by: Li Zhijian <lizhijian@fujitsu.com>
>> ---
>>   Documentation/arch/x86/exception-tables.rst | 2 +-
>>   1 file changed, 1 insertion(+), 1 deletion(-)
>>
>> diff --git a/Documentation/arch/x86/exception-tables.rst b/Documentation/arch/x86/exception-tables.rst
>> index efde1fef4fbd..562d1bc6d448 100644
>> --- a/Documentation/arch/x86/exception-tables.rst
>> +++ b/Documentation/arch/x86/exception-tables.rst
>> @@ -297,7 +297,7 @@ vma occurs?
>>      c) execution continues at local label 2 (address of the
>>         instruction immediately after the faulting user access).
>>   
>> -The steps 8a to 8c in a certain way emulate the faulting instruction.
>> +The steps a to c above in a certain way emulate the faulting instruction.
>>   
> 
> Those steps render as 1, 2, and 3 ... where did "a to c" come from?


>>>      c) execution continues at local label 2 (address of the
>>>         instruction immediately after the faulting user access).

IIUC, this is the __c__, and __a__ is documented above __c__.


Check the original commit, it did hardcode __8a__ and __8c__,
for example,

commit c368b4921bc6e309aba2fbee0efcbbc965008d9f
Author: Amerigo Wang <amwang@redhat.com>
Date:   Fri Jul 10 15:02:44 2009 -0700

     Doc: move Documentation/exception.txt into x86 subdir

<...snip...>

+1.) access to invalid address:
+ > c017e7a5 <do_con_write+e1> movb   (%ebx),%dl
+2.) MMU generates exception
+3.) CPU calls do_page_fault
+4.) do page fault calls search_exception_table (regs->eip == c017e7a5);
+5.) search_exception_table looks up the address c017e7a5 in the
+    exception table (i.e. the contents of the ELF section __ex_table)
+    and returns the address of the associated fault handle code c0199ff5.
+6.) do_page_fault modifies its own return address to point to the fault
+    handle code and returns.
+7.) execution continues in the fault handling code.
+8.) 8a) EAX becomes -EFAULT (== -14)
+    8b) DL  becomes zero (the value we "read" from user space)
+    8c) execution continues at local label 2 (address of the
+        instruction immediately after the faulting user access).
+
+The steps 8a to 8c in a certain way emulate the faulting instruction.
+
+That's it, mostly. If you look at our example, you might ask why


> 
> Thanks,
> 
> jon

Re: [PATCH] Documentation: exception-tables.rst: Fix the wrong steps referenced

[Jonathan Corbet]

Jonathan Corbet <corbet@lwn.net> writes:

> Li Zhijian <lizhijian@fujitsu.com> writes:
>
>> When it was in text format, it correctly hardcoded steps 8a to 8c.
>> However, after it was converted to RST, the sequence numbers were
>> auto-generated during rendering and became incorrect after some
>> steps were inserted.
>>
>> Change it to refer to steps a to c in a relative way.
>>
>> Signed-off-by: Li Zhijian <lizhijian@fujitsu.com>
>> ---
>>  Documentation/arch/x86/exception-tables.rst | 2 +-
>>  1 file changed, 1 insertion(+), 1 deletion(-)
>>
>> diff --git a/Documentation/arch/x86/exception-tables.rst b/Documentation/arch/x86/exception-tables.rst
>> index efde1fef4fbd..562d1bc6d448 100644
>> --- a/Documentation/arch/x86/exception-tables.rst
>> +++ b/Documentation/arch/x86/exception-tables.rst
>> @@ -297,7 +297,7 @@ vma occurs?
>>     c) execution continues at local label 2 (address of the
>>        instruction immediately after the faulting user access).
>>  
>> -The steps 8a to 8c in a certain way emulate the faulting instruction.
>> +The steps a to c above in a certain way emulate the faulting instruction.
>>  
>
> Those steps render as 1, 2, and 3 ... where did "a to c" come from?

Ah, I see where my confusion came from.

The fix is obvious: indent the line that was changed so that it is a
part of the bulleted item it's talking about.  I've applied your patch
with that change.

Thanks,

jon