From patchwork Wed May 30 20:13:11 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Logan Gunthorpe X-Patchwork-Id: 10439813 X-Patchwork-Delegate: bhelgaas@google.com Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id A0BD3601D3 for ; Wed, 30 May 2018 20:13:21 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 95DCF292F9 for ; Wed, 30 May 2018 20:13:21 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 941E529304; Wed, 30 May 2018 20:13:21 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00, MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 99BF52945A for ; Wed, 30 May 2018 20:13:19 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S932202AbeE3UNS (ORCPT ); Wed, 30 May 2018 16:13:18 -0400 Received: from ale.deltatee.com ([207.54.116.67]:49592 "EHLO ale.deltatee.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S932170AbeE3UNR (ORCPT ); Wed, 30 May 2018 16:13:17 -0400 Received: from cgy1-donard.priv.deltatee.com ([172.16.1.31]) by ale.deltatee.com with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1fO7T9-0002x3-RP; Wed, 30 May 2018 14:13:16 -0600 Received: from gunthorp by cgy1-donard.priv.deltatee.com with local (Exim 4.89) (envelope-from ) id 1fO7T7-0002wY-RV; Wed, 30 May 2018 14:13:13 -0600 From: Logan Gunthorpe To: linux-kernel@vger.kernel.org, linux-pci@vger.kernel.org, linux-ntb@googlegroups.com Cc: Logan Gunthorpe , Bjorn Helgaas , Alex Williamson , Doug Meyer Date: Wed, 30 May 2018 14:13:11 -0600 Message-Id: <20180530201311.11274-1-logang@deltatee.com> X-Mailer: git-send-email 2.11.0 X-SA-Exim-Connect-IP: 172.16.1.31 X-SA-Exim-Rcpt-To: linux-kernel@vger.kernel.org, linux-pci@vger.kernel.org, linux-ntb@googlegroups.com, logang@deltatee.com, bhelgaas@google.com, alex.williamson@redhat.com, dmeyer@gigaio.com X-SA-Exim-Mail-From: gunthorp@deltatee.com Subject: [PATCH v3] PCI: Expand documentation for pci_add_dma_alias() X-SA-Exim-Version: 4.2.1 (built Tue, 02 Aug 2016 21:08:31 +0000) X-SA-Exim-Scanned: Yes (on ale.deltatee.com) Sender: linux-pci-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-pci@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Seeing there's been some confusion about the use of pci_add_dma_alias(), expand the comment to describe why it must be called early and how early it must be called. Also, expand on the purpose of this function and common reasons it would be used. [The comment was reworded to some extent by Alex Williamson] Signed-off-by: Logan Gunthorpe Cc: Bjorn Helgaas Cc: Alex Williamson Cc: Doug Meyer --- v3: Fixed some typos pointed out by Randy v2: Reworked the patch with Alex's suggested wording drivers/pci/pci.c | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) -- 2.11.0 diff --git a/drivers/pci/pci.c b/drivers/pci/pci.c index dbfe7c4f3776..2d8650253cc9 100644 --- a/drivers/pci/pci.c +++ b/drivers/pci/pci.c @@ -5395,8 +5395,19 @@ int pci_set_vga_state(struct pci_dev *dev, bool decode, * @dev: the PCI device for which alias is added * @devfn: alias slot and function * - * This helper encodes 8-bit devfn as bit number in dma_alias_mask. - * It should be called early, preferably as PCI fixup header quirk. + * This helper encodes an 8-bit devfn as a bit number in dma_alias_mask + * which is used to program permissible bus-devfn source addresses for DMA + * requests in an IOMMU. These aliases factor into IOMMU group creation + * and are useful for devices generating DMA requests beyond or different + * from their logical bus-devfn. Examples include device quirks where the + * device simply uses the wrong devfn, as well as non-transparent bridges + * where the alias may be a proxy for devices in another domain. + * + * IOMMU group creation is performed during device discovery or addition, + * prior to any potential DMA mapping and therefore prior to driver probing + * (especially for userspace assigned devices where IOMMU group definition + * cannot be left as a userspace activity). DMA aliases should therefore + * be configured via quirks, such as the PCI fixup header quirk. */ void pci_add_dma_alias(struct pci_dev *dev, u8 devfn) {