From patchwork Tue Jan 16 13:19:10 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bogdan Purcareata X-Patchwork-Id: 10166881 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 8E03D601D3 for ; Tue, 16 Jan 2018 13:22:11 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 780352852E for ; Tue, 16 Jan 2018 13:22:11 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 6A1662852D; Tue, 16 Jan 2018 13:22:11 +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=-4.2 required=2.0 tests=BAD_ENC_HEADER,BAYES_00, DKIM_SIGNED, DKIM_VALID, RCVD_IN_DNSWL_MED autolearn=unavailable version=3.3.1 Received: from bombadil.infradead.org (bombadil.infradead.org [65.50.211.133]) (using TLSv1.2 with cipher AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id D89882852D for ; Tue, 16 Jan 2018 13:22:09 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=lists.infradead.org; s=bombadil.20170209; h=Sender: Content-Transfer-Encoding:Content-Type:Cc:List-Subscribe:List-Help:List-Post: List-Archive:List-Unsubscribe:List-Id:MIME-Version:References:In-Reply-To: Message-ID:Date:Subject:To:From:Reply-To:Content-ID:Content-Description: Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID: List-Owner; bh=A7UO8LCG2bk2IpWoU8Y7KwQ+xdX9y1IJrarBTrZ35VQ=; b=h6BBfG8y0RnMnW 1JaCBXFAn7JceR/9GgpUTmyw1d6GryyJaHks5M4ZrbGXk7sH8VtFb4bEBW2j9Gcf9j9qFsZXvRStO cf6PakFjDSd9frcM5pPDTOZ31PMjhwtt27T2yExcm2Mjjyprjkx75rb1Vnj9ssZcMdiaSEljYMVgD x53ipPepChfEb2bQFnqPUvuQdbil7rxd+GGAfndYddb08J4grtUhF87QHCCJfq2BY6+kMGCWfYHQB pM0kU9jgkVR6mMqaFvKLqewXdnjZ0JeiBChhZku5XOHuEJGXAmjN7MHlEbNNa6GcQNJu3Ohkxv3y7 cIFXjjrkLDybKTT6vZow==; Received: from localhost ([127.0.0.1] helo=bombadil.infradead.org) by bombadil.infradead.org with esmtp (Exim 4.89 #1 (Red Hat Linux)) id 1ebRBn-0007gL-Ux; Tue, 16 Jan 2018 13:22:07 +0000 Received: from mail-sn1nam02on0041.outbound.protection.outlook.com ([104.47.36.41] helo=NAM02-SN1-obe.outbound.protection.outlook.com) by bombadil.infradead.org with esmtps (Exim 4.89 #1 (Red Hat Linux)) id 1ebRA5-0003tQ-GA for linux-arm-kernel@lists.infradead.org; Tue, 16 Jan 2018 13:21:08 +0000 Received: from MWHPR03CA0020.namprd03.prod.outlook.com (10.175.133.158) by CY4PR03MB2695.namprd03.prod.outlook.com (10.173.43.138) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384_P256) id 15.20.407.7; Tue, 16 Jan 2018 13:20:09 +0000 Received: from BY2FFO11FD022.protection.gbl (2a01:111:f400:7c0c::156) by MWHPR03CA0020.outlook.office365.com (2603:10b6:300:117::30) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384) id 15.20.407.7 via Frontend Transport; Tue, 16 Jan 2018 13:20:09 +0000 Received-SPF: Fail (protection.outlook.com: domain of nxp.com does not designate 192.88.168.50 as permitted sender) receiver=protection.outlook.com; client-ip=192.88.168.50; helo=tx30smr01.am.freescale.net; Received: from tx30smr01.am.freescale.net (192.88.168.50) by BY2FFO11FD022.mail.protection.outlook.com (10.1.15.211) with Microsoft SMTP Server (version=TLS1_0, cipher=TLS_RSA_WITH_AES_256_CBC_SHA) id 15.20.345.12 via Frontend Transport; Tue, 16 Jan 2018 13:20:08 +0000 Received: from localhost.localdomain (fsr-ub1464-106.ea.freescale.net [10.171.82.96]) by tx30smr01.am.freescale.net (8.14.3/8.14.0) with ESMTP id w0GDJA14012166; Tue, 16 Jan 2018 06:20:04 -0700 From: Bogdan Purcareata To: , , Subject: [PATCH 8/8] staging: fsl-mc: Convert documentation to rst format Date: Tue, 16 Jan 2018 15:19:10 +0200 Message-ID: <1516108750-24938-9-git-send-email-bogdan.purcareata@nxp.com> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1516108750-24938-1-git-send-email-bogdan.purcareata@nxp.com> References: <1516108750-24938-1-git-send-email-bogdan.purcareata@nxp.com> X-EOPAttributedMessage: 0 X-Matching-Connectors: 131605824092077819; (91ab9b29-cfa4-454e-5278-08d120cd25b8); () X-Forefront-Antispam-Report: CIP:192.88.168.50; IPV:NLI; CTRY:US; EFV:NLI; SFV:NSPM; SFS:(10009020)(346002)(39380400002)(376002)(39860400002)(396003)(2980300002)(1110001)(1109001)(339900001)(199004)(189003)(6346003)(104016004)(5660300001)(26005)(39060400002)(97736004)(48376002)(50466002)(77096006)(49486002)(2950100002)(51416003)(4326008)(59450400001)(6636002)(6666003)(8936002)(8656006)(47776003)(16586007)(356003)(53936002)(2201001)(86362001)(36756003)(50226002)(81156014)(81166006)(8676002)(305945005)(53946003)(68736007)(2906002)(76176011)(316002)(106466001)(54906003)(7416002)(110136005)(498600001)(105606002); DIR:OUT; SFP:1101; SCL:1; SRVR:CY4PR03MB2695; H:tx30smr01.am.freescale.net; FPR:; SPF:Fail; PTR:InfoDomainNonexistent; A:1; MX:1; LANG:en; X-Microsoft-Exchange-Diagnostics: 1; BY2FFO11FD022; 1:x2nD1zSCVBdZ6waHJzJ23MCuh9HghRmCnd0EMd6mrhoYQbVRwE1QB1umZIA1EsMaQppldMdFcmZ9An/6Jsn2eD9Y7Ygdj3yiU0G8EbBrFY4J5vCZl/ahSYxE9MmOeV5O MIME-Version: 1.0 X-MS-PublicTrafficType: Email X-MS-Office365-Filtering-Correlation-Id: e3acab1a-74be-4cfc-7efb-08d55ce3ddd8 X-Microsoft-Antispam: UriScan:; BCL:0; PCL:0; RULEID:(7020095)(5600026)(4604075)(2017052603307); SRVR:CY4PR03MB2695; X-Microsoft-Exchange-Diagnostics: 1; CY4PR03MB2695; 3:M+/weZek8jRbOcEY7QFhW11HAyDi7y+oaTi+41yXQX7U9Hj2qRCwyKoZqItyMyugCPxiHL1ZqDYMUo3/sIpiRY+kczon+vNd5dQhaerUbF+eOqZtmFUqgZo6TGTqXTrqjLCqsgId3NL8QsOSm3BGaLnnSa5KwMYggRzbxzfkjVG3PigvutM8nTZYUzfvPWQPuvaHTYwgX//BaFNAyAmiJ8Q+wgAgotGV62LntNK8D+WX6c75DHkRlqL9qAZBh4zK6nWYv4/FChEF/wLklpsejE7WyF8UIGDDR71sV3oR/YsZTroKrTC/M68FIU/p+Xwwmly3Nt02HB/U762sjlWqbVCWAdtRIIeeBo1N2v3oNts=; 25:U2tcqpIQTPaqQwl4VlKrbCNdnXthf3eGVYXDRLL0gjr6S3bQpcj9pTKTZZU+xRscfen9e2CdTf6bHm9+NC3CYInQTQE/8lrk6pN91AfcCYHE4ooWq+6W5FMYxt3HVa5yDRdqCzLwzt+bWtnzOgcqQ3AU3wljhKnmnvWW/xzb8yqGNpiUUFKpB8T3d9XnoFFETFVHuywof6RPuTLOuX0yLcsewusl4lSuFQA/9kOvXaMQ8kUm8YlDP0M1NybgQqZr7hOO2TdE6rpirPooJOwH0tinIcColi6iavGwXOTHocWalZ9if9AyweoUAdh+RFMQX3oycZVx6QNcUyBZ+7r2tQ== X-MS-TrafficTypeDiagnostic: CY4PR03MB2695: X-Microsoft-Exchange-Diagnostics: 1; CY4PR03MB2695; 31:9so80eKbEomjE/6UsjM412MRsHeQ8rfPgB0C/RXNNbMUlYXAdbuAkvXC/4VeIxinb0Xcm8+EbDqVtX2/GuJepvKgC0TDzwvMhBKHoHX0JvqjUQ+iv3Tpo+yIaWBB23z/UFAra5Nx7O/diI6SWcffr+doGY/D6ELoiyvpmsphZwX8Q8zjOlhR8VVtmbh4/o4IgIKyt9CkW/romgea0aIo71gR8bXPPJKGLsXW4fSkF7E=; 4:RVIIVfxZJvg3k6ZshBHpHYynTs9CdpP7aPtr8qEouODEjQb8CaPzduDzHGo2CYedEhdIsQp5VAmTwTymf6n9ahh0aEkgjO+7GGnOoQK4EV/jN2zeAvEm0RcyLdN395SOvXHXOpv9ZbrA51QTbLo8eG7WumzSaD+l+q9qDHkUTXgThvOBvCdm1FyjpOYyHfaTyAngx/xuhmXEVy0j1N8aaPExOhvdRKt8E0PIZA681P8AdvoUYN2Ukk7NokYwruc6LC30KOIhHX9RNol9V4C7s4J9IJaPVlAGYT85aC1yx8zmFHDekEHQ9M7QSucDnnYRs9grd/L27dknKhq5o42cFXYVRwbRDcX6Sl5cvTFrYzt8fT2fceEwE4vQOpqh1H6cNjGx1XrgAybFOaEkLUPX7eManNwMYYoCl5VZEohMdIg= X-Microsoft-Antispam-PRVS: X-Exchange-Antispam-Report-Test: UriScan:(185117386973197)(227817650892897)(275809806118684)(21532816269658); X-Exchange-Antispam-Report-CFA-Test: BCL:0; PCL:0; RULEID:(6095135)(2401047)(8121501046)(5005006)(3002001)(93006095)(93001095)(3231023)(2400035)(944501161)(10201501046)(6055026)(6096035)(201703131430075)(201703131448075)(201703131433075)(201703151042153)(20161123559100)(20161123561025)(20161123565025)(20161123556025)(20161123563025)(201708071742011); SRVR:CY4PR03MB2695; BCL:0; PCL:0; RULEID:(100000803101)(100110400095)(400006); SRVR:CY4PR03MB2695; X-Forefront-PRVS: 0554B1F54F X-Microsoft-Exchange-Diagnostics: =?us-ascii?Q?1; CY4PR03MB2695; 23:YfeFfrXPcTlppg9sSDFL3VWMvk4QfVPlnVxVGkXT2?= =?us-ascii?Q?+7S2JB2Z6DCGQ9ueGxTANmkQ0/TmhNcGfqIPrynq0bfkejTQMxe3zK6yMD3G?= =?us-ascii?Q?NObbxiIhtrULZz0HDvb+UvQfN9gtr0TtscJ6LXB8mPiPQkcM/mxyrLfQ9Ae/?= =?us-ascii?Q?xEDa+RstKMg/KyUtmVe51SZGho+9pQZgUFx6tkWLtT28P1Z+1Dh9qkbrJmCi?= =?us-ascii?Q?eW3js6mN9HTq0WUf68KXrvjJia+dsjNbwzcFIBfT4VuhhL60eL+lHyoIQZe6?= =?us-ascii?Q?TyOrNFiwujLxPbFYC85p1sojph0pID3TfhiT4jVshZ+fa/Xab7ksuacXEksQ?= =?us-ascii?Q?CQ/QxXvGBGEoNQnHps2hoEVnpIVc8V9VOXjGR5aesVqAkIf7GqPdKMfkTWvy?= =?us-ascii?Q?kRjvTbqzOsmtjaiVk6f7EppiytwxSPTYb6LDt4+9TkNb3bW0iAjzK+ovSe7K?= =?us-ascii?Q?xHRhBylAB9k6p+MIziMycIqUIn74J35rJw0K1o3Zy/xpFVeq4ilyvueYwieB?= =?us-ascii?Q?1b7pOgTVcBz3atDTsS7VKV8lOOkunlsJlDLQrg+gwwTVRbXE6SpV9WsdPy6L?= =?us-ascii?Q?fd+r4PPvA2wrh8h0WdiAUNr88lGR7aA73T0SlFQvipb/QRe3aBE5KaZM0rA6?= =?us-ascii?Q?NvMjNXuWz9a2Um9BVRmYv8N8ZLSOjoH0SM41KOMKZ5v+HCf9Ecgtfp3CheR/?= =?us-ascii?Q?bzMp93VYjaoPdAS3JYfOSfYbSShUL/A9CV+tvykPOavUWcsf/cL8326K7xPi?= =?us-ascii?Q?9FMj/PP9MHh8kK681KEbWYezWjKnAfkdjJUjbcJRy0KVLD+MSs1vrBUfj47B?= =?us-ascii?Q?10GcGuNKB8oAXCCQ1CUXUTd4pWs2cJSaa1UkwG58SqFz3F+lGY3+3jUgfx5Q?= =?us-ascii?Q?UM8yN1gX+5NHg9AdN7aqjG0RLQEow9TkeByTTePp1wF4FVY/1Ny0wcdNZbf5?= =?us-ascii?Q?q5H2bYbBX2FxCWHYoqU5p/COc/TX8jOyEMU6F0msKHABeURmR3GhtAup5ItV?= =?us-ascii?Q?5b0KPRXbdiSTVHV5deU7Ori5txMxo/aA1LyXrAH/0t+MBNnXZTM34tZqE8X6?= =?us-ascii?Q?KFtn93/Yfb/91If1+OD7NoPcrvCarRtL4AwHdCmMYqyDAS8KKH+JvIqCKbNX?= =?us-ascii?Q?lfcFuFdJH5byv0DL5uSmMwMbq/LL9+OlTCE4AY15zfpFYsNuinpSz9v1LHvY?= =?us-ascii?Q?rLsVELhtRwIhYkxBJOwEPkyrapVDfJ0atY2?= X-Microsoft-Exchange-Diagnostics: 1; CY4PR03MB2695; 6:FexBCkLcC+wN1h41gzO5TOCPjV3THw9pgk9RyXL0wimeurIOvMyWEF00EE5kCj3hcMKYicj68PHNppBfP0OMYCeLUhXzSI4kJXABZhF88MV7RAKJGITAVDLv2tP/gpuWSKMeUAGvYIPJyQllQPJu/F8/NRPRATArOzzf35jO7a7N/EeZlpvuNsU73DIz9nKAKYhgukO5kBFB9ZLGgIVgRfIGeGbljoSqpbXqAbccVmv6feSN7f56uvo4ZiLebFlz5NraptQamBD8f20Fztc3Pk7Tcz6Qf6dRZR16scMIFMbr1eLRy1J4vwY54Is/YwTRKysm40dRGFZ1B+z8j4gMZ9DRoWRml9rT2oi3naL7sao=; 5:zc53EKWr2dqTA5qR2FsL5BvXN94OK9p1Sqr3L9gBuEHcoV1mtEL26AzU37K4hCXuB2BORET4TMKu87Wzc5euAA+a/OP3O9HIq/PUKLl0HCjJvKpMm7cXRnc/6oqmh0oNLWVAWYMj9E+ALu/qZNAqc6b7sCKo8OWFpZamzpsfZz8=; 24:BtfnQ8TB+yJFGUmNUWjHVP4zjPCf6nV5EHKMeYmGFYnOvgM3MXU0bAB3iKVYn8XYnXU6TTwjWlA3461F43RA1ds8rJntzOxPV+ZPWufheE8=; 7:ohxQeA8lDg7jZ2T9zkQ/KppVBDzZW+twWaVZS5mX+TaiUoionW/1F6OAX1nVIc1OZjTNHllPcP6RWeEye+IWNBHGQj9sL7szKcl/gAMFRUWLzhWSBIxDuvEVGy0ddbnhFC30udCaesLcC4mgGm4Br54m0agOdp7agdyuli/4vVULt08mnSqY87sxglDKEYEL2XIU0klDMsxPSgCRkQ1iPLqZVdCF7cb00MPdK8BsTvcpAqD62zN/Y3Ef2uiROTNT SpamDiagnosticOutput: 1:99 SpamDiagnosticMetadata: NSPM X-MS-Exchange-CrossTenant-OriginalArrivalTime: 16 Jan 2018 13:20:08.8645 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: e3acab1a-74be-4cfc-7efb-08d55ce3ddd8 X-MS-Exchange-CrossTenant-Id: 5afe0b00-7697-4969-b663-5eab37d5f47e X-MS-Exchange-CrossTenant-OriginalAttributedTenantConnectingIp: TenantId=5afe0b00-7697-4969-b663-5eab37d5f47e; Ip=[192.88.168.50]; Helo=[tx30smr01.am.freescale.net] X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem X-MS-Exchange-Transport-CrossTenantHeadersStamped: CY4PR03MB2695 X-CRM114-Version: 20100106-BlameMichelson ( TRE 0.8.0 (BSD) ) MR-646709E3 X-CRM114-CacheID: sfid-20180116_052022_731742_4E61033D X-CRM114-Status: GOOD ( 16.77 ) X-BeenThere: linux-arm-kernel@lists.infradead.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: devel@driverdev.osuosl.org, robh@kernel.org, stuyoder@gmail.com, arnd@arndb.de, marc.zyngier@arm.com, roy.pledge@nxp.com, ioana.ciornei@nxp.com, linux-kernel@vger.kernel.org, horia.geanta@nxp.com, nipun.gupta@nxp.com, tglx@linutronix.de, bogdan.purcareata@nxp.com, linux-arm-kernel@lists.infradead.org, jason@lakedaemon.net Sender: "linux-arm-kernel" Errors-To: linux-arm-kernel-bounces+patchwork-linux-arm=patchwork.kernel.org@lists.infradead.org X-Virus-Scanned: ClamAV using ClamSMTP From: Ioana Radulescu Update the doc file to comply with the rst format. It's not integrated into the documentation build structure yet, since it's still located in drivers/staging. Signed-off-by: Ioana Radulescu Reviewed-by: Laurentiu Tudor --- drivers/staging/fsl-mc/README.txt | 387 ---------------------------------- drivers/staging/fsl-mc/overview.rst | 404 ++++++++++++++++++++++++++++++++++++ 2 files changed, 404 insertions(+), 387 deletions(-) delete mode 100644 drivers/staging/fsl-mc/README.txt create mode 100644 drivers/staging/fsl-mc/overview.rst diff --git a/drivers/staging/fsl-mc/README.txt b/drivers/staging/fsl-mc/README.txt deleted file mode 100644 index 0ea5cd7..0000000 --- a/drivers/staging/fsl-mc/README.txt +++ /dev/null @@ -1,387 +0,0 @@ -Copyright (C) 2015 Freescale Semiconductor Inc. - -DPAA2 (Data Path Acceleration Architecture Gen2) Overview ---------------------------------------------------------- - -This document provides an overview of the Freescale DPAA2 architecture -and how it is integrated into the Linux kernel. - -Contents summary - -DPAA2 overview - -Overview of DPAA2 objects - -DPAA2 Linux driver architecture overview - -bus driver - -DPRC driver - -allocator - -DPIO driver - -Ethernet - -MAC - -Introduction ------------- - -DPAA2 is a hardware architecture designed for high-speeed network -packet processing. DPAA2 consists of sophisticated mechanisms for -processing Ethernet packets, queue management, buffer management, -autonomous L2 switching, virtual Ethernet bridging, and accelerator -(e.g. crypto) sharing. - -A DPAA2 hardware component called the Management Complex (or MC) manages the -DPAA2 hardware resources. The MC provides an object-based abstraction for -software drivers to use the DPAA2 hardware. - -The MC uses DPAA2 hardware resources such as queues, buffer pools, and -network ports to create functional objects/devices such as network -interfaces, an L2 switch, or accelerator instances. - -The MC provides memory-mapped I/O command interfaces (MC portals) -which DPAA2 software drivers use to operate on DPAA2 objects. - -The diagram below shows an overview of the DPAA2 resource management -architecture: - - +--------------------------------------+ - | OS | - | DPAA2 drivers | - | | | - +-----------------------------|--------+ - | - | (create,discover,connect - | config,use,destroy) - | - DPAA2 | - +------------------------| mc portal |-+ - | | | - | +- - - - - - - - - - - - -V- - -+ | - | | | | - | | Management Complex (MC) | | - | | | | - | +- - - - - - - - - - - - - - - -+ | - | | - | Hardware Hardware | - | Resources Objects | - | --------- ------- | - | -queues -DPRC | - | -buffer pools -DPMCP | - | -Eth MACs/ports -DPIO | - | -network interface -DPNI | - | profiles -DPMAC | - | -queue portals -DPBP | - | -MC portals ... | - | ... | - | | - +--------------------------------------+ - -The MC mediates operations such as create, discover, -connect, configuration, and destroy. Fast-path operations -on data, such as packet transmit/receive, are not mediated by -the MC and are done directly using memory mapped regions in -DPIO objects. - -Overview of DPAA2 Objects -------------------------- -The section provides a brief overview of some key DPAA2 objects. -A simple scenario is described illustrating the objects involved -in creating a network interfaces. - --DPRC (Datapath Resource Container) - - A DPRC is a container object that holds all the other - types of DPAA2 objects. In the example diagram below there - are 8 objects of 5 types (DPMCP, DPIO, DPBP, DPNI, and DPMAC) - in the container. - - +---------------------------------------------------------+ - | DPRC | - | | - | +-------+ +-------+ +-------+ +-------+ +-------+ | - | | DPMCP | | DPIO | | DPBP | | DPNI | | DPMAC | | - | +-------+ +-------+ +-------+ +---+---+ +---+---+ | - | | DPMCP | | DPIO | | - | +-------+ +-------+ | - | | DPMCP | | - | +-------+ | - | | - +---------------------------------------------------------+ - - From the point of view of an OS, a DPRC behaves similar to a plug and - play bus, like PCI. DPRC commands can be used to enumerate the contents - of the DPRC, discover the hardware objects present (including mappable - regions and interrupts). - - DPRC.1 (bus) - | - +--+--------+-------+-------+-------+ - | | | | | - DPMCP.1 DPIO.1 DPBP.1 DPNI.1 DPMAC.1 - DPMCP.2 DPIO.2 - DPMCP.3 - - Hardware objects can be created and destroyed dynamically, providing - the ability to hot plug/unplug objects in and out of the DPRC. - - A DPRC has a mappable MMIO region (an MC portal) that can be used - to send MC commands. It has an interrupt for status events (like - hotplug). - - All objects in a container share the same hardware "isolation context". - This means that with respect to an IOMMU the isolation granularity - is at the DPRC (container) level, not at the individual object - level. - - DPRCs can be defined statically and populated with objects - via a config file passed to the MC when firmware starts it. - --DPAA2 Objects for an Ethernet Network Interface - - A typical Ethernet NIC is monolithic-- the NIC device contains TX/RX - queuing mechanisms, configuration mechanisms, buffer management, - physical ports, and interrupts. DPAA2 uses a more granular approach - utilizing multiple hardware objects. Each object provides specialized - functions. Groups of these objects are used by software to provide - Ethernet network interface functionality. This approach provides - efficient use of finite hardware resources, flexibility, and - performance advantages. - - The diagram below shows the objects needed for a simple - network interface configuration on a system with 2 CPUs. - - +---+---+ +---+---+ - CPU0 CPU1 - +---+---+ +---+---+ - | | - +---+---+ +---+---+ - DPIO DPIO - +---+---+ +---+---+ - \ / - \ / - \ / - +---+---+ - DPNI --- DPBP,DPMCP - +---+---+ - | - | - +---+---+ - DPMAC - +---+---+ - | - port/PHY - - Below the objects are described. For each object a brief description - is provided along with a summary of the kinds of operations the object - supports and a summary of key resources of the object (MMIO regions - and IRQs). - - -DPMAC (Datapath Ethernet MAC): represents an Ethernet MAC, a - hardware device that connects to an Ethernet PHY and allows - physical transmission and reception of Ethernet frames. - -MMIO regions: none - -IRQs: DPNI link change - -commands: set link up/down, link config, get stats, - IRQ config, enable, reset - - -DPNI (Datapath Network Interface): contains TX/RX queues, - network interface configuration, and RX buffer pool configuration - mechanisms. The TX/RX queues are in memory and are identified by - queue number. - -MMIO regions: none - -IRQs: link state - -commands: port config, offload config, queue config, - parse/classify config, IRQ config, enable, reset - - -DPIO (Datapath I/O): provides interfaces to enqueue and dequeue - packets and do hardware buffer pool management operations. The DPAA2 - architecture separates the mechanism to access queues (the DPIO object) - from the queues themselves. The DPIO provides an MMIO interface to - enqueue/dequeue packets. To enqueue something a descriptor is written - to the DPIO MMIO region, which includes the target queue number. - There will typically be one DPIO assigned to each CPU. This allows all - CPUs to simultaneously perform enqueue/dequeued operations. DPIOs are - expected to be shared by different DPAA2 drivers. - -MMIO regions: queue operations, buffer management - -IRQs: data availability, congestion notification, buffer - pool depletion - -commands: IRQ config, enable, reset - - -DPBP (Datapath Buffer Pool): represents a hardware buffer - pool. - -MMIO regions: none - -IRQs: none - -commands: enable, reset - - -DPMCP (Datapath MC Portal): provides an MC command portal. - Used by drivers to send commands to the MC to manage - objects. - -MMIO regions: MC command portal - -IRQs: command completion - -commands: IRQ config, enable, reset - -Object Connections ------------------- - Some objects have explicit relationships that must - be configured: - - -DPNI <--> DPMAC - -DPNI <--> DPNI - -DPNI <--> L2-switch-port - A DPNI must be connected to something such as a DPMAC, - another DPNI, or L2 switch port. The DPNI connection - is made via a DPRC command. - - +-------+ +-------+ - | DPNI | | DPMAC | - +---+---+ +---+---+ - | | - +==========+ - - -DPNI <--> DPBP - A network interface requires a 'buffer pool' (DPBP - object) which provides a list of pointers to memory - where received Ethernet data is to be copied. The - Ethernet driver configures the DPBPs associated with - the network interface. - -Interrupts ----------- - All interrupts generated by DPAA2 objects are message - interrupts. At the hardware level message interrupts - generated by devices will normally have 3 components-- - 1) a non-spoofable 'device-id' expressed on the hardware - bus, 2) an address, 3) a data value. - - In the case of DPAA2 devices/objects, all objects in the - same container/DPRC share the same 'device-id'. - For ARM-based SoC this is the same as the stream ID. - - -DPAA2 Linux Drivers Overview ----------------------------- - -This section provides an overview of the Linux kernel drivers for -DPAA2-- 1) the bus driver and associated "DPAA2 infrastructure" -drivers and 2) functional object drivers (such as Ethernet). - -As described previously, a DPRC is a container that holds the other -types of DPAA2 objects. It is functionally similar to a plug-and-play -bus controller. - -Each object in the DPRC is a Linux "device" and is bound to a driver. -The diagram below shows the Linux drivers involved in a networking -scenario and the objects bound to each driver. A brief description -of each driver follows. - - +------------+ - | OS Network | - | Stack | - +------------+ +------------+ - | Allocator |. . . . . . . | Ethernet | - |(DPMCP,DPBP)| | (DPNI) | - +-.----------+ +---+---+----+ - . . ^ | - . . | | dequeue> - +-------------+ . | | - | DPRC driver | . +---+---V----+ +---------+ - | (DPRC) | . . . . . .| DPIO driver| | MAC | - +----------+--+ | (DPIO) | | (DPMAC) | - | +------+-----+ +-----+---+ - | | | - | | | - +----+--------------+ | +--+---+ - | MC-bus driver | | | PHY | - | | | |driver| - | /bus/fsl-mc | | +--+---+ - +-------------------+ | | - | | - ================================ HARDWARE =========|=================|====== - DPIO | - | | - DPNI---DPBP | - | | - DPMAC | - | | - PHY ---------------+ - ===================================================|======================== - -A brief description of each driver is provided below. - - MC-bus driver - ------------- - The MC-bus driver is a platform driver and is probed from a - node in the device tree (compatible "fsl,qoriq-mc") passed in by boot - firmware. It is responsible for bootstrapping the DPAA2 kernel - infrastructure. - Key functions include: - -registering a new bus type named "fsl-mc" with the kernel, - and implementing bus call-backs (e.g. match/uevent/dev_groups) - -implementing APIs for DPAA2 driver registration and for device - add/remove - -creates an MSI IRQ domain - -doing a 'device add' to expose the 'root' DPRC, in turn triggering - a bind of the root DPRC to the DPRC driver - The binding for the MC-bus device-tree node can be consulted here: - Documentation/devicetree/bindings/misc/fsl,qoriq-mc.txt - The sysfs bind/unbind interfaces for the MC-bus can be consulted here: - Documentation/ABI/testing/sysfs-bus-fsl-mc* - - DPRC driver - ----------- - The DPRC driver is bound to DPRC objects and does runtime management - of a bus instance. It performs the initial bus scan of the DPRC - and handles interrupts for container events such as hot plug by - re-scanning the DPRC. - - Allocator - ---------- - Certain objects such as DPMCP and DPBP are generic and fungible, - and are intended to be used by other drivers. For example, - the DPAA2 Ethernet driver needs: - -DPMCPs to send MC commands, to configure network interfaces - -DPBPs for network buffer pools - - The allocator driver registers for these allocatable object types - and those objects are bound to the allocator when the bus is probed. - The allocator maintains a pool of objects that are available for - allocation by other DPAA2 drivers. - - DPIO driver - ----------- - The DPIO driver is bound to DPIO objects and provides services that allow - other drivers such as the Ethernet driver to enqueue and dequeue data for - their respective objects. - Key services include: - -data availability notifications - -hardware queuing operations (enqueue and dequeue of data) - -hardware buffer pool management - - To transmit a packet the Ethernet driver puts data on a queue and - invokes a DPIO API. For receive, the Ethernet driver registers - a data availability notification callback. To dequeue a packet - a DPIO API is used. - - There is typically one DPIO object per physical CPU for optimum - performance, allowing different CPUs to simultaneously enqueue - and dequeue data. - - The DPIO driver operates on behalf of all DPAA2 drivers - active in the kernel-- Ethernet, crypto, compression, - etc. - - Ethernet driver - --------------- - The Ethernet driver is bound to a DPNI and implements the kernel - interfaces needed to connect the DPAA2 network interface to - the network stack. - - Each DPNI corresponds to a Linux network interface. - - MAC driver - ---------- - An Ethernet PHY is an off-chip, board specific component and is managed - by the appropriate PHY driver via an mdio bus. The MAC driver - plays a role of being a proxy between the PHY driver and the - MC. It does this proxy via the MC commands to a DPMAC object. - If the PHY driver signals a link change, the MAC driver notifies - the MC via a DPMAC command. If a network interface is brought - up or down, the MC notifies the DPMAC driver via an interrupt and - the driver can take appropriate action. diff --git a/drivers/staging/fsl-mc/overview.rst b/drivers/staging/fsl-mc/overview.rst new file mode 100644 index 0000000..79fede4 --- /dev/null +++ b/drivers/staging/fsl-mc/overview.rst @@ -0,0 +1,404 @@ +.. include:: + +DPAA2 (Data Path Acceleration Architecture Gen2) Overview +========================================================= + +:Copyright: |copy| 2015 Freescale Semiconductor Inc. +:Copyright: |copy| 2018 NXP + +This document provides an overview of the Freescale DPAA2 architecture +and how it is integrated into the Linux kernel. + +Introduction +============ + +DPAA2 is a hardware architecture designed for high-speeed network +packet processing. DPAA2 consists of sophisticated mechanisms for +processing Ethernet packets, queue management, buffer management, +autonomous L2 switching, virtual Ethernet bridging, and accelerator +(e.g. crypto) sharing. + +A DPAA2 hardware component called the Management Complex (or MC) manages the +DPAA2 hardware resources. The MC provides an object-based abstraction for +software drivers to use the DPAA2 hardware. +The MC uses DPAA2 hardware resources such as queues, buffer pools, and +network ports to create functional objects/devices such as network +interfaces, an L2 switch, or accelerator instances. +The MC provides memory-mapped I/O command interfaces (MC portals) +which DPAA2 software drivers use to operate on DPAA2 objects. + +The diagram below shows an overview of the DPAA2 resource management +architecture:: + + +--------------------------------------+ + | OS | + | DPAA2 drivers | + | | | + +-----------------------------|--------+ + | + | (create,discover,connect + | config,use,destroy) + | + DPAA2 | + +------------------------| mc portal |-+ + | | | + | +- - - - - - - - - - - - -V- - -+ | + | | | | + | | Management Complex (MC) | | + | | | | + | +- - - - - - - - - - - - - - - -+ | + | | + | Hardware Hardware | + | Resources Objects | + | --------- ------- | + | -queues -DPRC | + | -buffer pools -DPMCP | + | -Eth MACs/ports -DPIO | + | -network interface -DPNI | + | profiles -DPMAC | + | -queue portals -DPBP | + | -MC portals ... | + | ... | + | | + +--------------------------------------+ + + +The MC mediates operations such as create, discover, +connect, configuration, and destroy. Fast-path operations +on data, such as packet transmit/receive, are not mediated by +the MC and are done directly using memory mapped regions in +DPIO objects. + +Overview of DPAA2 Objects +========================= + +The section provides a brief overview of some key DPAA2 objects. +A simple scenario is described illustrating the objects involved +in creating a network interfaces. + +DPRC (Datapath Resource Container) +---------------------------------- + +A DPRC is a container object that holds all the other +types of DPAA2 objects. In the example diagram below there +are 8 objects of 5 types (DPMCP, DPIO, DPBP, DPNI, and DPMAC) +in the container. + +:: + + +---------------------------------------------------------+ + | DPRC | + | | + | +-------+ +-------+ +-------+ +-------+ +-------+ | + | | DPMCP | | DPIO | | DPBP | | DPNI | | DPMAC | | + | +-------+ +-------+ +-------+ +---+---+ +---+---+ | + | | DPMCP | | DPIO | | + | +-------+ +-------+ | + | | DPMCP | | + | +-------+ | + | | + +---------------------------------------------------------+ + +From the point of view of an OS, a DPRC behaves similar to a plug and +play bus, like PCI. DPRC commands can be used to enumerate the contents +of the DPRC, discover the hardware objects present (including mappable +regions and interrupts). + +:: + + DPRC.1 (bus) + | + +--+--------+-------+-------+-------+ + | | | | | + DPMCP.1 DPIO.1 DPBP.1 DPNI.1 DPMAC.1 + DPMCP.2 DPIO.2 + DPMCP.3 + +Hardware objects can be created and destroyed dynamically, providing +the ability to hot plug/unplug objects in and out of the DPRC. + +A DPRC has a mappable MMIO region (an MC portal) that can be used +to send MC commands. It has an interrupt for status events (like +hotplug). +All objects in a container share the same hardware "isolation context". +This means that with respect to an IOMMU the isolation granularity +is at the DPRC (container) level, not at the individual object +level. + +DPRCs can be defined statically and populated with objects +via a config file passed to the MC when firmware starts it. + +DPAA2 Objects for an Ethernet Network Interface +----------------------------------------------- + +A typical Ethernet NIC is monolithic-- the NIC device contains TX/RX +queuing mechanisms, configuration mechanisms, buffer management, +physical ports, and interrupts. DPAA2 uses a more granular approach +utilizing multiple hardware objects. Each object provides specialized +functions. Groups of these objects are used by software to provide +Ethernet network interface functionality. This approach provides +efficient use of finite hardware resources, flexibility, and +performance advantages. + +The diagram below shows the objects needed for a simple +network interface configuration on a system with 2 CPUs. + +:: + + +---+---+ +---+---+ + CPU0 CPU1 + +---+---+ +---+---+ + | | + +---+---+ +---+---+ + DPIO DPIO + +---+---+ +---+---+ + \ / + \ / + \ / + +---+---+ + DPNI --- DPBP,DPMCP + +---+---+ + | + | + +---+---+ + DPMAC + +---+---+ + | + port/PHY + +Below the objects are described. For each object a brief description +is provided along with a summary of the kinds of operations the object +supports and a summary of key resources of the object (MMIO regions +and IRQs). + +DPMAC (Datapath Ethernet MAC) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Represents an Ethernet MAC, a hardware device that connects to an Ethernet +PHY and allows physical transmission and reception of Ethernet frames. + +- MMIO regions: none +- IRQs: DPNI link change +- commands: set link up/down, link config, get stats, + IRQ config, enable, reset + +DPNI (Datapath Network Interface) +Contains TX/RX queues, network interface configuration, and RX buffer pool +configuration mechanisms. The TX/RX queues are in memory and are identified +by queue number. + +- MMIO regions: none +- IRQs: link state +- commands: port config, offload config, queue config, + parse/classify config, IRQ config, enable, reset + +DPIO (Datapath I/O) +~~~~~~~~~~~~~~~~~~~ +Provides interfaces to enqueue and dequeue +packets and do hardware buffer pool management operations. The DPAA2 +architecture separates the mechanism to access queues (the DPIO object) +from the queues themselves. The DPIO provides an MMIO interface to +enqueue/dequeue packets. To enqueue something a descriptor is written +to the DPIO MMIO region, which includes the target queue number. +There will typically be one DPIO assigned to each CPU. This allows all +CPUs to simultaneously perform enqueue/dequeued operations. DPIOs are +expected to be shared by different DPAA2 drivers. + +- MMIO regions: queue operations, buffer management +- IRQs: data availability, congestion notification, buffer + pool depletion +- commands: IRQ config, enable, reset + +DPBP (Datapath Buffer Pool) +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Represents a hardware buffer pool. + +- MMIO regions: none +- IRQs: none +- commands: enable, reset + +DPMCP (Datapath MC Portal) +~~~~~~~~~~~~~~~~~~~~~~~~~~ +Provides an MC command portal. +Used by drivers to send commands to the MC to manage +objects. + +- MMIO regions: MC command portal +- IRQs: command completion +- commands: IRQ config, enable, reset + +Object Connections +================== +Some objects have explicit relationships that must +be configured: + +- DPNI <--> DPMAC +- DPNI <--> DPNI +- DPNI <--> L2-switch-port + + A DPNI must be connected to something such as a DPMAC, + another DPNI, or L2 switch port. The DPNI connection + is made via a DPRC command. + +:: + + +-------+ +-------+ + | DPNI | | DPMAC | + +---+---+ +---+---+ + | | + +==========+ + +- DPNI <--> DPBP + + A network interface requires a 'buffer pool' (DPBP + object) which provides a list of pointers to memory + where received Ethernet data is to be copied. The + Ethernet driver configures the DPBPs associated with + the network interface. + +Interrupts +========== +All interrupts generated by DPAA2 objects are message +interrupts. At the hardware level message interrupts +generated by devices will normally have 3 components-- +1) a non-spoofable 'device-id' expressed on the hardware +bus, 2) an address, 3) a data value. + +In the case of DPAA2 devices/objects, all objects in the +same container/DPRC share the same 'device-id'. +For ARM-based SoC this is the same as the stream ID. + + +DPAA2 Linux Drivers Overview +============================ + +This section provides an overview of the Linux kernel drivers for +DPAA2-- 1) the bus driver and associated "DPAA2 infrastructure" +drivers and 2) functional object drivers (such as Ethernet). + +As described previously, a DPRC is a container that holds the other +types of DPAA2 objects. It is functionally similar to a plug-and-play +bus controller. +Each object in the DPRC is a Linux "device" and is bound to a driver. +The diagram below shows the Linux drivers involved in a networking +scenario and the objects bound to each driver. A brief description +of each driver follows. + +:: + + +------------+ + | OS Network | + | Stack | + +------------+ +------------+ + | Allocator |. . . . . . . | Ethernet | + |(DPMCP,DPBP)| | (DPNI) | + +-.----------+ +---+---+----+ + . . ^ | + . . | | dequeue> + +-------------+ . | | + | DPRC driver | . +---+---V----+ +---------+ + | (DPRC) | . . . . . .| DPIO driver| | MAC | + +----------+--+ | (DPIO) | | (DPMAC) | + | +------+-----+ +-----+---+ + | | | + | | | + +--------+----------+ | +--+---+ + | MC-bus driver | | | PHY | + | | | |driver| + | /bus/fsl-mc | | +--+---+ + +-------------------+ | | + | | + ========================= HARDWARE =========|=================|====== + DPIO | + | | + DPNI---DPBP | + | | + DPMAC | + | | + PHY ---------------+ + ============================================|======================== + +A brief description of each driver is provided below. + +MC-bus driver +------------- +The MC-bus driver is a platform driver and is probed from a +node in the device tree (compatible "fsl,qoriq-mc") passed in by boot +firmware. It is responsible for bootstrapping the DPAA2 kernel +infrastructure. +Key functions include: + +- registering a new bus type named "fsl-mc" with the kernel, + and implementing bus call-backs (e.g. match/uevent/dev_groups) +- implementing APIs for DPAA2 driver registration and for device + add/remove +- creates an MSI IRQ domain +- doing a 'device add' to expose the 'root' DPRC, in turn triggering + a bind of the root DPRC to the DPRC driver + +The binding for the MC-bus device-tree node can be consulted at +*Documentation/devicetree/bindings/misc/fsl,qoriq-mc.txt*. +The sysfs bind/unbind interfaces for the MC-bus can be consulted at +*Documentation/ABI/testing/sysfs-bus-fsl-mc*. + +DPRC driver +----------- +The DPRC driver is bound to DPRC objects and does runtime management +of a bus instance. It performs the initial bus scan of the DPRC +and handles interrupts for container events such as hot plug by +re-scanning the DPRC. + +Allocator +--------- +Certain objects such as DPMCP and DPBP are generic and fungible, +and are intended to be used by other drivers. For example, +the DPAA2 Ethernet driver needs: + +- DPMCPs to send MC commands, to configure network interfaces +- DPBPs for network buffer pools + +The allocator driver registers for these allocatable object types +and those objects are bound to the allocator when the bus is probed. +The allocator maintains a pool of objects that are available for +allocation by other DPAA2 drivers. + +DPIO driver +----------- +The DPIO driver is bound to DPIO objects and provides services that allow +other drivers such as the Ethernet driver to enqueue and dequeue data for +their respective objects. +Key services include: + +- data availability notifications +- hardware queuing operations (enqueue and dequeue of data) +- hardware buffer pool management + +To transmit a packet the Ethernet driver puts data on a queue and +invokes a DPIO API. For receive, the Ethernet driver registers +a data availability notification callback. To dequeue a packet +a DPIO API is used. +There is typically one DPIO object per physical CPU for optimum +performance, allowing different CPUs to simultaneously enqueue +and dequeue data. + +The DPIO driver operates on behalf of all DPAA2 drivers +active in the kernel-- Ethernet, crypto, compression, +etc. + +Ethernet driver +--------------- +The Ethernet driver is bound to a DPNI and implements the kernel +interfaces needed to connect the DPAA2 network interface to +the network stack. +Each DPNI corresponds to a Linux network interface. + +MAC driver +---------- +An Ethernet PHY is an off-chip, board specific component and is managed +by the appropriate PHY driver via an mdio bus. The MAC driver +plays a role of being a proxy between the PHY driver and the +MC. It does this proxy via the MC commands to a DPMAC object. +If the PHY driver signals a link change, the MAC driver notifies +the MC via a DPMAC command. If a network interface is brought +up or down, the MC notifies the DPMAC driver via an interrupt and +the driver can take appropriate action.