Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
Date:   Tue, 22 Dec 2020 10:59:22 -0800
From:   Sean Christopherson <seanjc@google.com>
To:     Borislav Petkov <bp@alien8.de>
Cc:     Jonathan Corbet <corbet@lwn.net>, x86-ml <x86@kernel.org>,
        lkml <linux-kernel@vger.kernel.org>
Subject: Re: [PATCH] Documentation/submitting-patches: Add blurb about
 backtraces in commit messages
Message-ID: <X+JCCqTJkgZASj7T@google.com>
References: <20201217183756.GE23634@zn.tnic>
 <20201221095425.6da68163@lwn.net>
 <20201222130555.GA13463@zn.tnic>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <20201222130555.GA13463@zn.tnic>
Precedence: bulk

On Tue, Dec 22, 2020, Borislav Petkov wrote:
> Ok, here's the next one which I think, is also, not really controversial.

Heh, are you trying to jinx yourself?

> diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
> index 5ba54120bef7..0ffb21366381 100644
> --- a/Documentation/process/submitting-patches.rst
> +++ b/Documentation/process/submitting-patches.rst
> @@ -679,6 +679,26 @@ generates appropriate diffstats by default.)
>  See more details on the proper patch format in the following
>  references.
>  
> +Backtraces in commit mesages
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +Backtraces help document the call chain leading to a problem. However,
> +not all backtraces are helpful. For example, early boot call chains are
> +unique and obvious.

I'd argue that there is still value in the backtrace though, e.g. I find them
very helpful when doing git archaeology.  A backtrace is an easily recognizable
signature (don't have to read a bunch of text to understand there was a splat of
some kind), and the call stack is often helpful even if it is unique, e.g. for
unfamiliar code (including early boot chains) and/or code that is substantially
different from the current upstream.

> Copying the full dmesg output verbatim, however,
> +adds distracting information like timestamps, module lists, register and
> +stack dumps.
> +
> +Therefore, the most useful backtraces should distill the relevant
> +information from the dump, which makes it easier to focus on the real
> +issue. Here is an example of a well-trimmed backtrace::
> +
> +  unchecked MSR access error: WRMSR to 0xd51 (tried to write 0x0000000000000064)
> +  at rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20)
> +  Call Trace:
> +  mba_wrmsr
> +  update_domains
> +  rdtgroup_mkdir
> +
>  .. _explicit_in_reply_to:

I'd prefer not to encourage people to strip the info after the function name,
though I do agree it's somewhat distracting (especially the offset/size).  The
module, call site in the function, exact file/line if available, etc... provides
context that I find helpful for building a mental model of what went wrong.
E.g. which modules are in play, which short wrapper functions can likely be
glossed over, etc...