[PATCH v2] Documentation: x86: Fix obsolete name of page fault handler

[PATCH v2] Documentation: x86: Fix obsolete name of page fault handler

[Chin En Lin]

Since commit 91eeafea1e4b ("x86/entry: Switch page fault exception to
IDTENTRY_RAW"), the function name of the page fault handler is out of date.
And because of commit aa37c51b9421 ("x86/mm: Break out user address space
handling"), the description of search_exception_table is not correct
anymore. It may mislead the user who wants to use the documentation to
figure out the page fault handler.

Also, fix typo and add the parentheses after function and macro name.

Signed-off-by: Chin En Lin <shiyn.lin@gmail.com>
---
 Documentation/x86/exception-tables.rst | 23 +++++++++++++----------
 1 file changed, 13 insertions(+), 10 deletions(-)

diff --git a/Documentation/x86/exception-tables.rst b/Documentation/x86/exception-tables.rst
index de58110c5ffd..efde1fef4fbd 100644
--- a/Documentation/x86/exception-tables.rst
+++ b/Documentation/x86/exception-tables.rst
@@ -32,14 +32,14 @@ Whenever the kernel tries to access an address that is currently not
 accessible, the CPU generates a page fault exception and calls the
 page fault handler::
 
-  void do_page_fault(struct pt_regs *regs, unsigned long error_code)
+  void exc_page_fault(struct pt_regs *regs, unsigned long error_code)
 
 in arch/x86/mm/fault.c. The parameters on the stack are set up by
 the low level assembly glue in arch/x86/entry/entry_32.S. The parameter
 regs is a pointer to the saved registers on the stack, error_code
 contains a reason code for the exception.
 
-do_page_fault first obtains the unaccessible address from the CPU
+exc_page_fault() first obtains the inaccessible address from the CPU
 control register CR2. If the address is within the virtual address
 space of the process, the fault probably occurred, because the page
 was not swapped in, write protected or something similar. However,
@@ -57,10 +57,10 @@ Where does fixup point to?
 
 Since we jump to the contents of fixup, fixup obviously points
 to executable code. This code is hidden inside the user access macros.
-I have picked the get_user macro defined in arch/x86/include/asm/uaccess.h
+I have picked the get_user() macro defined in arch/x86/include/asm/uaccess.h
 as an example. The definition is somewhat hard to follow, so let's peek at
 the code generated by the preprocessor and the compiler. I selected
-the get_user call in drivers/char/sysrq.c for a detailed examination.
+the get_user() call in drivers/char/sysrq.c for a detailed examination.
 
 The original code in sysrq.c line 587::
 
@@ -281,12 +281,15 @@ vma occurs?
 
     > c017e7a5 <do_con_write+e1> movb   (%ebx),%dl
 #. MMU generates exception
-#. CPU calls do_page_fault
-#. do page fault calls search_exception_table (regs->eip == c017e7a5);
-#. search_exception_table looks up the address c017e7a5 in the
+#. CPU calls exc_page_fault()
+#. exc_page_fault() calls do_user_addr_fault()
+#. do_user_addr_fault() calls kernelmode_fixup_or_oops()
+#. kernelmode_fixup_or_oops() calls fixup_exception() (regs->eip == c017e7a5);
+#. fixup_exception() calls search_exception_tables()
+#. search_exception_tables() 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.
-#. do_page_fault modifies its own return address to point to the fault
+#. fixup_exception() modifies its own return address to point to the fault
    handle code and returns.
 #. execution continues in the fault handling code.
 #. a) EAX becomes -EFAULT (== -14)
@@ -298,9 +301,9 @@ 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
 we set EAX to -EFAULT in the exception handler code. Well, the
-get_user macro actually returns a value: 0, if the user access was
+get_user() macro actually returns a value: 0, if the user access was
 successful, -EFAULT on failure. Our original code did not test this
-return value, however the inline assembly code in get_user tries to
+return value, however the inline assembly code in get_user() tries to
 return -EFAULT. GCC selected EAX to return this value.
 
 NOTE:
-- 
2.25.1

Re: [PATCH v2] Documentation: x86: Fix obsolete name of page fault handler

[Jonathan Corbet]

Chin En Lin <shiyn.lin@gmail.com> writes:

> Since commit 91eeafea1e4b ("x86/entry: Switch page fault exception to
> IDTENTRY_RAW"), the function name of the page fault handler is out of date.
> And because of commit aa37c51b9421 ("x86/mm: Break out user address space
> handling"), the description of search_exception_table is not correct
> anymore. It may mislead the user who wants to use the documentation to
> figure out the page fault handler.
>
> Also, fix typo and add the parentheses after function and macro name.

"Also" in a changelog like this is an indication that you've moved on to
an independent change that should be done as its own patch.  That is
certainly true of typo fixes and such, which should be separated out
from more substantive changes.

> Signed-off-by: Chin En Lin <shiyn.lin@gmail.com>
> ---
>  Documentation/x86/exception-tables.rst | 23 +++++++++++++----------
>  1 file changed, 13 insertions(+), 10 deletions(-)

Nonetheless, the patch seems clear enough and nobody has objected, so
I've applied it.

Thanks,

jon