Re: [PATCH v2 1/3] x86/entry/64: Document idtentry

[Borislav Petkov]

On Mon, Sep 03, 2018 at 03:59:42PM -0700, Andy Lutomirski wrote:
> The idtentry macro is complicated and magical.  Document what it
> does to help future readers and to allow future patches to adjust
> the code and docs at the same time.
> 
> Signed-off-by: Andy Lutomirski <luto@xxxxxxxxxx>
> ---
>  arch/x86/entry/entry_64.S | 35 +++++++++++++++++++++++++++++++++++
>  arch/x86/kernel/traps.c   |  4 ++++
>  2 files changed, 39 insertions(+)
> 
> diff --git a/arch/x86/entry/entry_64.S b/arch/x86/entry/entry_64.S
> index 957dfb693ecc..1796c42e08af 100644
> --- a/arch/x86/entry/entry_64.S
> +++ b/arch/x86/entry/entry_64.S
> @@ -900,6 +900,41 @@ apicinterrupt IRQ_WORK_VECTOR			irq_work_interrupt		smp_irq_work_interrupt
>   */
>  #define CPU_TSS_IST(x) PER_CPU_VAR(cpu_tss_rw) + (TSS_ist + ((x) - 1) * 8)
>  
> +/**
> + * idtentry - Generate an IDT entry stub
> + * @sym: Name of the generated entry point
> + * @do_sym: C function to be called
> + * @has_error_code: True if this IDT vector has an error code on the stack
> + * @paranoid: non-zero means that this vector may be invoked from kernel
> + *            mode with user GSBASE and/or user CR3.  2 is special -- see below.
> + * @shift_ist: Set to an IST index if entries from kernel mode should
> + *             decrement the IST stack so that nested entries get a fresh
> + *             stack.  (This is for #DB, which has a nasty habit of
> + *             recursing.)
> + *
> + * idtentry generates an IDT stub that sets up a usable kernel context,
> + * creates struct pt_regs, and calls @do_sym.  The stub has the following
> + * special behaviors:
> + *
> + * On an entry from user mode, the stub switches from the trampoline or
> + * IST stack to the normal thread stack.  On an exit to user mode, the
> + * normal exit-to-usermode path is invoked.
> + *
> + * On an exit to kernel mode, if paranoid == 0, we check for preemption,

				   @paranoid

Otherwise, documenting our entry maze is always a good idea!

Reviewed-by: Borislav Petkov <bp@xxxxxxx>

-- 
Regards/Gruss,
    Boris.

Good mailing practices for 400: avoid top-posting and trim the reply.