Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Date:   Wed, 16 Nov 2022 13:31:10 -0400
From:   Jason Gunthorpe <jgg@nvidia.com>
To:     Thomas Gleixner <tglx@linutronix.de>
Cc:     LKML <linux-kernel@vger.kernel.org>, x86@kernel.org,
        Joerg Roedel <joro@8bytes.org>, Will Deacon <will@kernel.org>,
        linux-pci@vger.kernel.org, Bjorn Helgaas <bhelgaas@google.com>,
        Lorenzo Pieralisi <lorenzo.pieralisi@arm.com>,
        Marc Zyngier <maz@kernel.org>,
        Greg Kroah-Hartman <gregkh@linuxfoundation.org>,
        Dave Jiang <dave.jiang@intel.com>,
        Alex Williamson <alex.williamson@redhat.com>,
        Kevin Tian <kevin.tian@intel.com>,
        Dan Williams <dan.j.williams@intel.com>,
        Logan Gunthorpe <logang@deltatee.com>,
        Ashok Raj <ashok.raj@intel.com>, Jon Mason <jdmason@kudzu.us>,
        Allen Hubbe <allenbh@gmail.com>,
        "Ahmed S. Darwish" <darwi@linutronix.de>,
        Reinette Chatre <reinette.chatre@intel.com>,
        Michael Ellerman <mpe@ellerman.id.au>,
        Christophe Leroy <christophe.leroy@csgroup.eu>,
        linuxppc-dev@lists.ozlabs.org
Subject: Re: [patch 31/39] Documentation: PCI: Add reference to PCI/MSI
 device driver APIs
Message-ID: <Y3UeXiH4wzUPmtGL@nvidia.com>
References: <20221111120501.026511281@linutronix.de>
 <20221111122015.397739421@linutronix.de>
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <20221111122015.397739421@linutronix.de>
MIME-Version: 1.0
X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1
X-MS-Exchange-AntiSpam-MessageData-0: =?us-ascii?Q?9mgb7qZBKA6p5zPND9J6a5snnBUSWg+iQARY9RCXy9WDN88idkZ6bvZ1U1M1?=
 =?us-ascii?Q?w4xdkLr+LP0/wEnYM8As6dCGPo4Jq2pWcyhiBgI6oUITMrBwbbUFyXHjb6T+?=
 =?us-ascii?Q?yhLfp345ZrHTEriJM091yILnCsYgqDVwTInMgK4hB6MTqfDDKG4o0PlssTbv?=
 =?us-ascii?Q?TlUNejX1lsvu+OBP5JP6PzAt++8C43/IfK+0StXuT7VbzLU2hxrt9Jkuhzht?=
 =?us-ascii?Q?Eaxs3O7M9LYpJe+rLRKddz6SNdAm0gwv8e9pFNIBUg43LP0Ph1mzS/6pdU8M?=
 =?us-ascii?Q?JduM+S9xRr6WeS697Tfd9WnGGoj6KO66kOBZvwVPfL4Yv+HqMwUtji4bavsN?=
 =?us-ascii?Q?Pd6a0aIi2L4HY9LRvhHWSkDZFFOU/yBQKssrC8cbD9CtBW/3GiojMKtJq4hm?=
 =?us-ascii?Q?/PqglZISG8X7qbWi2ov27XLab30h36gMS9wbHjzQF7In5UL7MNoxctD0uw5Y?=
 =?us-ascii?Q?/9j9z/3gneRWP4LP9jh5/g5CypsooBZHOoVAiP28T5jJIlTzhve13LG7tnIY?=
 =?us-ascii?Q?10sdW/lbW8nre1wKDEAZHkffR83HLRGv1IBP/DxjzQcr7QXwOqCeJuPpR1m5?=
 =?us-ascii?Q?Lzq1aEzUQV4dI045Khnha0v4OFbnISrETs4h3asKzCQcInaI7ToYP3Mg+K6X?=
 =?us-ascii?Q?rj9hTytpZlSfaIL98/2GSKnQZCcTOB2zjd69+uYEaHEPqIEZr0lkCCp/RC65?=
 =?us-ascii?Q?u/eVg6XUkjutYBoHvEtleOevZkRKmo+iqcCOgdl4SlvpOIV6qqt60aqYouwi?=
 =?us-ascii?Q?MRAgio8v2sECvWALBgHTOlo8O8R4rvHzvI5Cjg4HPHf/sCd0DVvV5lmBd2CS?=
 =?us-ascii?Q?iwex/usZydDRQwLzTbe31QiYGoGGFvZikXwqvFPoGlSfFoEHq2jxP5TxEGis?=
 =?us-ascii?Q?GkDd5CgCUrlCFbLSwhWjZuWQINTx+WXdiYtXmWhByT+s+VvGP3qfj6LXNbkw?=
 =?us-ascii?Q?+VIk5rh4XbYLK/14huk6SHn+857l/kO12KENG/fOxgYG6gEhJFqdjJq+lMtP?=
 =?us-ascii?Q?kz8DKvw5Wi7B3UnREJVDoVtREXpV8rolte55DW34eLXnmP+6QAnzYvNZWl+o?=
 =?us-ascii?Q?lWt/hE4ayJx7vbcqP0LkGvu+xTHjg3gVB0O27Q1jKL5rZLMTzpEqID8TsgUq?=
 =?us-ascii?Q?VhoDkpTJ/4tX7YszYNCf/MYx2yfqVmecJjQVOxJhlUoLiukXmJ9sfJRQcAme?=
 =?us-ascii?Q?7k2Q0zL78ucOGkK1OO2b8IJ3HIyO5uLXaSi8GDqdoJx6ZINwnLwLZVup1/Ok?=
 =?us-ascii?Q?YsotNuzqG2+CwwZL/rafim5vk2ud0qtlIOJoAUubf0xWCxEZxjrtCxfzAm3s?=
 =?us-ascii?Q?z918MnpIW/K0QvsyBnsXdJWap1WolgvC3drlqZe4mSQOCd4iokJ9t3VjdXTv?=
 =?us-ascii?Q?OTaBcSV4nGdJrRYY683sQu5U+YS4k5rwhbLNlbOiOewcx4hg4kvdiz8ATv7X?=
 =?us-ascii?Q?kFaEH8WYAELo0R51GVOYshQh0j8BUWkWiwkcV7r/NXTWiDM9UJTxGZwaermN?=
 =?us-ascii?Q?yF7AtV9RPGDI1yPKnmNp0/IuwNugHu80HhTSs0sOvQf5QmkmTjGwUkW7QIZH?=
 =?us-ascii?Q?7GwyUAtEFmMD1xteXm0v6QrdM2r83AZKOaNA3JYa?=
X-OriginatorOrg: Nvidia.com
X-MS-Exchange-CrossTenant-Network-Message-Id: f4062918-6037-45e6-a598-08dac7f85bf6
X-MS-Exchange-CrossTenant-AuthSource: LV2PR12MB5869.namprd12.prod.outlook.com
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 16 Nov 2022 17:31:13.7397
 (UTC)
X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted
X-MS-Exchange-CrossTenant-Id: 43083d15-7273-40c1-b7db-39efd9ccc17a
X-MS-Exchange-CrossTenant-MailboxType: HOSTED
X-MS-Exchange-CrossTenant-UserPrincipalName: 4/yHo2KlvZLaI7alMVa58iAV0om42p3DNHe+/YVxDCMgDwDrZRGSlW8ihVAr+Rb7
X-MS-Exchange-Transport-CrossTenantHeadersStamped: SA1PR12MB7295
X-Spam-Status: No, score=-1.1 required=5.0 tests=BAYES_00,DKIMWL_WL_HIGH,
        DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,FORGED_SPF_HELO,
        RCVD_IN_DNSWL_NONE,RCVD_IN_MSPIKE_H2,SPF_HELO_PASS,SPF_NONE
        autolearn=no autolearn_force=no version=3.4.6
X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on
        lindbergh.monkeyblade.net
Precedence: bulk
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org

On Fri, Nov 11, 2022 at 02:55:04PM +0100, Thomas Gleixner wrote:
> From: Ahmed S. Darwish <darwi@linutronix.de>
> 
> All exported device-driver MSI APIs are now grouped in one place at
> drivers/pci/msi/api.c with comprehensive kernel-docs added.
> 
> Reference these kernel-docs in the official PCI/MSI howto.
> 
> Signed-off-by: Ahmed S. Darwish <darwi@linutronix.de>
> Signed-off-by: Thomas Gleixner <tglx@linutronix.de>
> 
> ---
>  Documentation/PCI/msi-howto.rst |   10 ++++++++++
>  1 file changed, 10 insertions(+)

I was wondering what the payoff was for moving everything to api.c,
this seems pretty good.

Though, in some regards it might be cleaner to teach ":export:" about
how to process symbol namespaces and put all the architecture facing
exports in some PCI_MSI_ARCH/IRQCHIP namespace which could achieve the
same effect for kdoc as moving all the code around and have the bonus
of discouraging people from mis-using the APIs inside inappropriate
drivers.

But, I like the idea, and the outcome is great so

Reviewed-by: Jason Gunthorpe <jgg@nvidia.com>

Jason