Re: [PATCH RFC 07/15] Documentation: Interrupt Message store

From: Jason Gunthorpe <jgg@ziepe.ca>
To: "Dey, Megha" <megha.dey@linux.intel.com>
Cc: Dave Jiang <dave.jiang@intel.com>,
	vkoul@kernel.org, maz@kernel.org, bhelgaas@google.com,
	rafael@kernel.org, gregkh@linuxfoundation.org,
	tglx@linutronix.de, hpa@zytor.com, alex.williamson@redhat.com,
	jacob.jun.pan@intel.com, ashok.raj@intel.com, yi.l.liu@intel.com,
	baolu.lu@intel.com, kevin.tian@intel.com,
	sanjay.k.kumar@intel.com, tony.luck@intel.com,
	jing.lin@intel.com, dan.j.williams@intel.com,
	kwankhede@nvidia.com, eric.auger@redhat.com, parav@mellanox.com,
	dmaengine@vger.kernel.org, linux-kernel@vger.kernel.org,
	x86@kernel.org, linux-pci@vger.kernel.org, kvm@vger.kernel.org
Subject: Re: [PATCH RFC 07/15] Documentation: Interrupt Message store
Date: Sun, 3 May 2020 19:28:55 -0300	[thread overview]
Message-ID: <20200503222855.GT26002@ziepe.ca> (raw)
In-Reply-To: <afd2ae49-ed65-5cde-c867-a923ac9bf8ac@linux.intel.com>

On Fri, May 01, 2020 at 03:32:22PM -0700, Dey, Megha wrote:
> Hi Jason,
> 
> On 4/23/2020 1:04 PM, Jason Gunthorpe wrote:
> > On Tue, Apr 21, 2020 at 04:34:30PM -0700, Dave Jiang wrote:
> > 
> > > diff --git a/Documentation/ims-howto.rst b/Documentation/ims-howto.rst
> > > new file mode 100644
> > > index 000000000000..a18de152b393
> > > +++ b/Documentation/ims-howto.rst
> > > @@ -0,0 +1,210 @@
> > > +.. SPDX-License-Identifier: GPL-2.0
> > > +.. include:: <isonum.txt>
> > > +
> > > +==========================
> > > +The IMS Driver Guide HOWTO
> > > +==========================
> > > +
> > > +:Authors: Megha Dey
> > > +
> > > +:Copyright: 2020 Intel Corporation
> > > +
> > > +About this guide
> > > +================
> > > +
> > > +This guide describes the basics of Interrupt Message Store (IMS), the
> > > +need to introduce a new interrupt mechanism, implementation details of
> > > +IMS in the kernel, driver changes required to support IMS and the general
> > > +misconceptions and FAQs associated with IMS.
> > 
> > I'm not sure why we need to call this IMS in kernel documentat? I know
> > Intel is using this term, but this document is really only talking
> > about extending the existing platform_msi stuff, which looks pretty
> > good actually.
> 
> hmmm, so maybe we call it something else or just say dynamic platform-msi?
> 
> > 
> > A lot of this is good for the cover letter..
> 
> Well, I got a lot of comments internally and externally about how the cover
> page needs to have just the basics and all the ugly details can go in the
> Documentation. So well, I am confused here.

Documentation should be documentation for users and developers.

Justification and rational for why functionality should be merged
belong in the commit message and cover letter, IMHO.

Here too much time is spent belabouring IMS's rational and not enough
is spent explaining how a driver should consume it or how a platform
should provide it.

And since most of this tightly related to platform-msi it might make
sense to start by documenting platform msi then adding a diff on that
to explain what change is being made to accommodate IMS.

Most likely few people are very familiar with platform-msi in the
first place..

Jason