From mboxrd@z Thu Jan 1 00:00:00 1970 From: Subject: [PATCH v12 1/6] fpga: add usage documentation for simple fpga bus Date: Tue, 27 Oct 2015 17:09:10 -0500 Message-ID: <1445983755-24007-2-git-send-email-atull@opensource.altera.com> References: <1445983755-24007-1-git-send-email-atull@opensource.altera.com> Mime-Version: 1.0 Content-Type: text/plain Return-path: In-Reply-To: <1445983755-24007-1-git-send-email-atull@opensource.altera.com> Sender: linux-kernel-owner@vger.kernel.org To: gregkh@linuxfoundation.org Cc: Moritz Fischer , Josh Cartwright , monstr@monstr.eu, michal.simek@xilinx.com, Rob Herring , Pawel Moll , Mark Rutland , Ian Campbell , Kumar Gala , Jonathan Corbet , linux-kernel@vger.kernel.org, devicetree@vger.kernel.org, linux-doc@vger.kernel.org, pantelis.antoniou@konsulko.com, delicious.quinoa@gmail.com, dinguyen@opensource.altera.com, Alan Tull List-Id: devicetree@vger.kernel.org From: Alan Tull Add a document spelling out usage of the simple fpga bus. Signed-off-by: Alan Tull --- v9: Initial version of this patch in patchset v10: s/fpga/FPGA/g improve formatting some rewriting move to staging/simple-fpga-bus v11: No change in this patch for v11 of the patch set v12: Moved out of staging Small changes due to using FPGA bridge framework and not representing the bridges as resets. --- Documentation/fpga/simple-fpga-bus.txt | 58 ++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 Documentation/fpga/simple-fpga-bus.txt diff --git a/Documentation/fpga/simple-fpga-bus.txt b/Documentation/fpga/simple-fpga-bus.txt new file mode 100644 index 0000000..bd43478 --- /dev/null +++ b/Documentation/fpga/simple-fpga-bus.txt @@ -0,0 +1,58 @@ +Simple FPGA Bus + +Alan Tull 2015 + +Overview +======== + +The simple FPGA bus adds device tree overlay support for FPGA's. Loading a +DT overlay will result in the FPGA getting an image loaded, its bridges will +be released, and the DT populated for nodes below the simple-fpga-bus. This +results in drivers getting probed for the hardware that just got added. This +is intended to support the FPGA usage where the FPGA has hardware that +requires drivers. Removing the overlay will result in the drivers getting +removed and the bridges being disabled. + +The simple FPGA bus will need to disable and enable bridges that will only +affect the child devices that are below the bus. If partial reconfiguration +is to be done, then bridges will need to be added within the FPGA design to +protect the rest of the bus when one part of the FPGA design is being +reconfigured. + + +Sequence +======== + +Load the DT overlay. One way to do that from user space is to use Pantelis' +DT-Overlay configfs interface. + +This causes the simple FPGA bus go be probed and will do the following: + 1. Disable the FPGA bridges. + 2. Call the FPGA manager core to program the FPGA. + 3. Release the FPGA bridges. + 4. Call of_platform_populate resulting in device drivers getting probed. + + +Requirements +============ + + 1. An FPGA image that has a hardware block or blocks that use drivers that are + supported in the kernel. + 2. A device tree overlay (example is in the simple-fpga-bus bindings document). + 3. A FPGA manager driver supporting writing the FPGA. + 4. FPGA bridge drivers. + +The DT overlay includes bindings (documented in bindings/simple-fpga-bus.txt) +that specify: + * Which FPGA manager to use. + * Which image file to load. + * Flags indicating whether this this image is for full reconfiguration or + partial. + * A list of FPGA bridges. + * Child nodes specifying the devices that will be added with appropriate + compatible strings, etc. + +Since this code uses the firmware interface to get the image and DT overlay, +they currently have to be files on the file system. It doesn't have to be that +way forever as DT bindings could be added to point to other sources for the +image. -- 1.7.9.5 From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1755008AbbJ0WU7 (ORCPT ); Tue, 27 Oct 2015 18:20:59 -0400 Received: from mail-bn1on0081.outbound.protection.outlook.com ([157.56.110.81]:43424 "EHLO na01-bn1-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1754651AbbJ0WQV (ORCPT ); Tue, 27 Oct 2015 18:16:21 -0400 Authentication-Results: spf=fail (sender IP is 66.35.236.227) smtp.mailfrom=opensource.altera.com; lwn.net; dkim=none (message not signed) header.d=none;lwn.net; dmarc=none action=none header.from=opensource.altera.com; Authentication-Results: spf=none (sender IP is ) smtp.mailfrom=atull@opensource.altera.com; From: To: CC: Moritz Fischer , Josh Cartwright , , , Rob Herring , Pawel Moll , Mark Rutland , Ian Campbell , "Kumar Gala" , Jonathan Corbet , , , , , , , Alan Tull Subject: [PATCH v12 1/6] fpga: add usage documentation for simple fpga bus Date: Tue, 27 Oct 2015 17:09:10 -0500 Message-ID: <1445983755-24007-2-git-send-email-atull@opensource.altera.com> X-Mailer: git-send-email 1.7.9.5 In-Reply-To: <1445983755-24007-1-git-send-email-atull@opensource.altera.com> References: <1445983755-24007-1-git-send-email-atull@opensource.altera.com> MIME-Version: 1.0 Content-Type: text/plain X-Originating-IP: [64.129.157.38] X-ClientProxiedBy: BY1PR20CA0021.namprd20.prod.outlook.com (25.162.140.31) To CY1PR03MB1517.namprd03.prod.outlook.com (25.163.17.23) X-Microsoft-Exchange-Diagnostics-untrusted: 1;CY1PR03MB1517;2:fAFwqlFs7M5pUsWGrKZh+RbjhobGesGBqxOw75qZ55i31ZUTOANeOi5rxQp64kteZSpuOqnF1NllojV3GSvVZgDGj8OMjKy25MdJMVjdgC9buP5IjE08jUjOFIDaZ1CJjgzIn/EalQ2PvzxC9ST7dybHXVCBaD+lLYmLzmYJczg=;3:0IuxrhNy1vtCBbnhdRYskgWuy54Q9rQkqzTZBclC2oib4AHa9oA92QzY709fKxfumXDYvJuJIbEl3oDhVfAUjYgUba262Nfo/cxWrKE6vosKQweUBM5HynidpJGCfhjazrTZf1F5hYH/AV+WGa94qA==;25:5jtAUSevtxeCBx/SHk/BqhZ3zZk9Kx4TI7/ckjWQjzCuHXQ5aNwvGRiYXpfkqjOziQYxuXg5BsZd9LEH12Eg69DNfc8qWtY6Mr412A1PbMDfcr3V+xbcjHiYTmzw5GqJXckYtkKJ7mGOHfYBwSk22ktH+pOnu8egnwOH9JO9qCPXPe5UGkO6jNJDnJAuArqb/heOZMNY3zJMjTZlvkAgWHyCmbMdF4Piy0sP7AuPrvmV3B4riomPrNOE1soDEdGrLdncBG8dvSz9gZLnBPC5eQ==;20:uVcnsIl26nL4J4imDIMOyuh8rGJZqLksOiFtsaBt6190vekfHZGRlbYhaK+1iqjHoUeUIfp9tN07+6fmFjVfuMfv80vlqoGGSHM/timhuKLQRd03NEPS36mXm9UceK4DwPO3otrG8AFr7ZDniVOg8NFm3bmbnQ4xDSS4u+wkPqk= X-Microsoft-Antispam-Untrusted: UriScan:;BCL:0;PCL:0;RULEID:;SRVR:CY1PR03MB1517; X-Microsoft-Antispam-PRVS: X-Exchange-Antispam-Report-Test: UriScan:(80048183373757)(204874498639787);UriScan:(80048183373757)(204874498639787); X-Exchange-Antispam-Report-CFA-Test: BCL:0;PCL:0;RULEID:(601004)(2401047)(8121501046)(5005006)(520078)(3002001)(10201501037)(102215026);SRVR:CY1PR03MB1517;BCL:0;PCL:0;RULEID:;SRVR:CY1PR03MB1517;BCL:0;PCL:0;RULEID:(601004)(2401047)(8121501046)(520078)(5005006)(3002001)(102215026);SRVR:BLUPR03MB033;BCL:0;PCL:0;RULEID:;SRVR:BLUPR03MB033; X-Microsoft-Exchange-Diagnostics-untrusted: 1;CY1PR03MB1517;4:D03/OL6JPPOrl0AASDwgC/0B6tXuO6o+mmKQ6tPiF3OI6E1smTH3r6+DseFZrksFVXCiRpr6hH3lnQ+X3VVPKYntcmB4KBjLtG0OGBnonblgQAnAYC5+Kn9aNyFK/siRHOKUEjHylWy5bJ83QG8nhuagyyI73fRCEVdN6IU+PBAb5wu8VeagMQoGUTmveCnTPC6dQeBE8d6LXYhYBt7kKaep3Aq++tZ6LYpTyke+pU3C1zFQkIgLwAoWntm5N/iE87SoGjqRsnQI12SA59QhYrM+DBjCbEL8DRe2Y5n7jOFVsLQtKT/TPOr0kLo0qvTNYYnTOKFiDA5OxlW2RjAmS5IDpXqHhWweLVM4an+TLTEJbnbMgU8aa59YZycGzz1Oq/JaDuwgzzXGdWeKLpdCNQ== X-Forefront-PRVS: 0742443479 X-Forefront-Antispam-Report-Untrusted: SFV:NSPM;SFS:(10009020)(6009001)(199003)(189002)(2351001)(50226001)(19580405001)(19580395003)(229853001)(92566002)(5003940100001)(33646002)(40100003)(106356001)(69596002)(105586002)(110136002)(101416001)(2950100001)(5001960100002)(122386002)(107886002)(97736004)(86362001)(77096005)(81156007)(86152002)(5008740100001)(4001430100002)(66066001)(5007970100001)(47776003)(5004730100002)(189998001)(87976001)(50986999)(76176999)(53416004)(48376002)(42186005)(50466002)(7059030);DIR:OUT;SFP:1101;SCL:1;SRVR:CY1PR03MB1517;H:linuxheads99.altera.com;FPR:;SPF:None;PTR:InfoNoRecords;A:0;MX:1;LANG:en; X-Microsoft-Exchange-Diagnostics-untrusted: =?us-ascii?Q?1;CY1PR03MB1517;23:Fb6b4pzQSeIjHdvUEqkU2MxwbA0UIWtBOAp/J6ZIJ?= =?us-ascii?Q?HE71djWoRz8a5EHQLgB2l5RGYwCw5ajSvGWreAM51/Q6sZSFkFloxg+e/Sgu?= =?us-ascii?Q?TX3OVwFV+d/MEMFXdXI3So5XPcbQcDIGZLLWYknrohWcgy2HxS41XSIuwCyZ?= =?us-ascii?Q?ekszWf69DsBz85qkLUPH+1S7LH2fK+s+6X9e6QiClRcTy6TmmVV+tdPh+Y44?= =?us-ascii?Q?mv7L2H4HUdTGo4uokzYMTfOHAZwiahnLOteJIejnqtZt0Lev2zg9DK2EMsfZ?= =?us-ascii?Q?BSJqEXKZllZ1VXxjm7AvOq0Cd7x8AODGVOIWh8juarUzG8jkNyK2WJAIKMHx?= =?us-ascii?Q?USKFhN0lydXbr122cG4uK/N5+d0JiMr1chIAJxP9epvVCt/S4CmhmW+JarZY?= =?us-ascii?Q?ZjOQBEN0HgRXT99v/tCIPI7Kbf+IsCglZp7+d52fRt6KcwFiiH4TRULoiYde?= =?us-ascii?Q?sVKcMmUvTwAGudKp0z6JFJjwMlz57kZcvgyG5Hgn2lh4wGc/RXdoMJQ5UphN?= =?us-ascii?Q?RfQd9b/XbwdYX/KzrjMK6P9U2KkNU/Jcr15512dMuARS+/evktD+NYxwQ/Jr?= =?us-ascii?Q?3lXctX2JTB6zeu4MSDGji5Kz8WZfxxwnBNHUyBJQjc616R22Msna3kPLZ0fm?= =?us-ascii?Q?aFrqj2a0tqhZ3rqqgEIE3E518R/yEtuxpj+6lx4HDFfEwFtJDcKrDFIhVoR6?= =?us-ascii?Q?v+hAGxKwnQOOr4wXUawM/ctQFmf/DXv1owCIet9OkoGP/pU+V+KlEFUYvHK8?= =?us-ascii?Q?32AMPFVYm3ltOg2plVne37L3hbTzX0dZvkH3Gs/NbooSIWEGRxPGNuBNg7En?= =?us-ascii?Q?Yq0QuZcf29Yrm4/FGd1yqcMfMogHvWo1McA0HMZ0lWkVcdelOcn9/7xp9yEp?= =?us-ascii?Q?29piPCIsrtka80sVaJ8q3LU9A6rTOMWTvi4NBK6Q79ZSyzUgqCjKrjEu8sN8?= =?us-ascii?Q?1I9kMzfReLTOBR8skiMdL9CNMp6DlVA68CgIN9BdliEdXs86SOvntD0G70R1?= =?us-ascii?Q?OpyfdgqiA8pdGLsa4CWcEAgcZCQ/olD+ZHsFrEz2Gkng9wgycSZ6AGE70Tij?= =?us-ascii?Q?UDXl/aNLRy/zxb6g04T9ruq6RqYVh0XbOVib6ep23Vedu+EkSQgvK479uPWU?= =?us-ascii?Q?oOlu8a/O/A=3D?= X-Microsoft-Exchange-Diagnostics-untrusted: 1;CY1PR03MB1517;5:U/eL7YKrYxCbogSmb6tg4KZjFQjh7iSpn9q5qLK2OZ1nq9s3NdLnJseTAqoo4fMXA3ypdXUKgz8qZnaW1sfVDkAJDc+0pxsDfQ1k3dB4XdSpBIu+rPU0iHVu0mT54q84Jqj4NQ/VgiOG5SdZ73heSg==;24:+eJbhkz3MPEc8cnfjhuSi8QvmXN61Jw7o1GLsa2bwRMTUwu2GoHQRuTHkervhXkiJbcnRIHIF6jptr0yjNoc+4jx7NUZgUs22FSVFSXyrJs=;20:/Ho+oiVGaGFS/UFj/ka7Vye46kjfpZmwHswNPYuCDDB7QJBuVOy39jG9XS/2rxl/I6s7kHsZ0Hf8FLDwPfcP7DLGIBm/KIfk2b8rmcNuy9w2vzKBPm6w1/JkQkUDWCPvXhcCndD/Co2rJN9g2rAWJ1vKmm68HLAGzv4n+Ugv07I= SpamDiagnosticOutput: 1:23 SpamDiagnosticMetadata: NSPM X-MS-Exchange-Transport-CrossTenantHeadersStamped: CY1PR03MB1517 X-EOPAttributedMessage: 0 X-MS-Exchange-Transport-CrossTenantHeadersStripped: BY2FFO11FD039.protection.gbl X-Microsoft-Exchange-Diagnostics: 1;BY2FFO11FD039;1:uBP2XqrsMT2aN6950WkenkRYcrbg65Hcg46HQaCZlMr3RxPzFdpoKFuV/QLVN+EOLd1dAVZMlP++skwcfVJ4B7RK0AkWj6j9fXRFvixgkHwrmeOOQ/PHC19HX7oSawkSRUaQO5UVdupgPx/qsIR4dLUVGAnmcCigCmEjBrMt6Xb76t9I90Bi8XVGeWhO11LL5JzEbv/oNuObywqq1uPRc2zUPN66hcW9Bs4hYmJLPaRgbBH24PCGcCHCc0v4XdzJss6cXV2JacJcyTO7yHOUguGv22jtCTayh8dUe5YNs+EuZ9m9lBYa6v+ut3nxLvpvfWOL2JvUOQ0GqSvGKgwg4V+hiu47BypKbrLE73xXirhpDAES0gze3xAwpXMlX2SVMXD+LBZinwFLf4qwQBzh9Q== X-Forefront-Antispam-Report: CIP:66.35.236.227;CTRY:US;IPV:NLI;EFV:NLI;SFV:NSPM;SFS:(10009020)(6009001)(2980300002)(1110001)(1109001)(339900001)(189002)(199003)(107886002)(50986999)(76176999)(2351001)(48376002)(47776003)(86152002)(85426001)(87936001)(16796002)(50466002)(33646002)(66066001)(5008740100001)(5004730100002)(6806005)(106466001)(229853001)(5007970100001)(77096005)(2950100001)(92566002)(110136002)(4001430100002)(5001920100001)(50226001)(6070500001)(5001960100002)(19580405001)(97736004)(86362001)(105606002)(81156007)(19580395003)(53416004)(189998001)(122386002)(40100003)(5003940100001)(7099028)(7059030);DIR:OUT;SFP:1101;SCL:1;SRVR:BLUPR03MB033;H:sj-itexedge03.altera.priv.altera.com;FPR:;SPF:Fail;PTR:InfoDomainNonexistent;MX:1;A:0;LANG:en; X-Microsoft-Exchange-Diagnostics: 1;BLUPR03MB033;2:qh+0RRDk2jBYKI0pjTNHiX7faI3Zh1Ls7HYcVhqPPMdo8qcql0jYpRGv9IYnabvUK0eKbwlNnhH2222tXuBoQ9G7L8/F/722Gl4fxxVq3lcJEwrIR9jnelX4JJqf390j7gdfv3CtweON0aWO02qs6v0UH7/WxhH6JPLgsPxVFdQ=;3:p6pvJmkDaQ+RlTUNX0Ha7SO2F/2UHa9Sk9eUte+scfQZF4ofwiVvA+4xfM5OZSD0qYuDFck9D/TpQnn7LJlTKIf9Uvr/h4Wk/0vhtZRs9emUf6VNeErSNFxe9gH+xsXmMyZKvVGn/DE7GHlnusZzTV/CSxNTxK8fr8LSxG66OkIqh0q67jSAEM97Wj5aLhv3fui07F0t+qxjENRsNfvylYucAwcmb5if/KMfxIhIr84=;25:MgnY21bCFyK1f7GGWgmwJeX7IvVwiKVSz3HxhmMKAPIXyLJaO5bOAqCIGiViusjjmZ4mTdk/R6u2lQWO5qmYDLyBBpBIkhR9DTU24xfLT9f/buNhCvJ/8BT37ZzqMnxB1BPyabym7ibkftnj8xw4K90fxr6tSJ5VkDSIXkNLdsrPkk0dQZ9//wqXfMFvzGhAhuHaAMSPW5ASakZ0IEKIG5s/RrW5YNtjekrNI17A1N2RnGsKhb4CZ3fQUBRx8JKCZp0W4CvXhUy3vLNN7eoFiQ==;20:XEqXfCDONePv/9bveHjffasfm+K9Fdh4aIqJe58wdvc3rG3/wDprUrsWDaNrJG0tHSbWcfCq2niVxEhXzJmddK5+1gOtbcm+00ptL8YOQYlIjcuMTM7qfZ2GFchlj5CD1fyICvPjFfDlk7iV8+7iSQ/8v6nJ58lfcEyjOdVupRo= X-Microsoft-Antispam: UriScan:;BCL:0;PCL:0;RULEID:;SRVR:BLUPR03MB033; X-Microsoft-Exchange-Diagnostics: 1;BLUPR03MB033;4:asGj2Gr9+AGYQmGqgJouXd/ob4WjY/0lp+Etzvae7gMA7iMzRasQlh79iZ49eNq89a/gIgx7KUePgZzM7NkDVrZMDcOmyUTpLYm83xhSsfrCLMh6zFhZ0VVuRZmp9shcmLAmut3FyInXdYV+fmizFUuiXSbIO/7ETrN424u+7r48qABdREqSt63st4yaXAcbuERgcJn7OiC7AUmH1OHsqstcYJijmPyJ/DjWsPC2LEGUChmbDYrFjI42oJA7Nsq/r9z+J9vGj0cAx549HyFP3H+OzT/m0lkBElOtSKfGhDd77OG4gISRo8Qbgf3IC6wA30V5Y1Mdd3DcF/3LVye+14YE6t8VC1gkgyo2ghoI0sdLRIMOCHueLwnHd1Kx0vDd X-Forefront-PRVS: 0742443479 X-Microsoft-Exchange-Diagnostics: =?us-ascii?Q?1;BLUPR03MB033;23:noQYI58+OGzipR1TGzvowuvCkGrPmOv1niuZcOTbyo?= =?us-ascii?Q?F+u9zuAzpsLyXPletodEKn2L5BgUclG2Z3L+sBb3kf7jlPbnUiVBgb2zhKRe?= =?us-ascii?Q?5586dlYuRUKPdrlVYWMHNx39Y83vhTYqNqwtFBJZhoG1+xkaShLZY6jhwkzy?= =?us-ascii?Q?h4r6d66kHZVHWhfgERIBUXM6xvp1TKQFRsw5NGFIFxvqm245zccCnMhOmnwa?= =?us-ascii?Q?Ld/YaC4La/1gNw07Nmk6OWwGCgDQ48gFIE+QqdlUmjVrVjn3NtVGT3Rb9r9y?= =?us-ascii?Q?nnXO1lb2nQapRkRXlSTziZI1vQf2PinsR/wPW0Bp4D32Ok7aaWWeLLl5Npxk?= =?us-ascii?Q?9jPegJMsckIfOaalVdcWB1u5XtHyMquOcUw8ICxHqer/dR58I+bHu0lc+KxZ?= =?us-ascii?Q?Bv0EjOTO0EUk1i5RjUmB2WBdtaU2QnyHCxMEAYEQoSALeS23OKlUXGSY6o+A?= =?us-ascii?Q?OY1XGBrmbMVpv/UGV09KrAKObgeV/Cyemw9Sma6udUOCv85qsbVjS5QxGHkL?= =?us-ascii?Q?+AgxOoyAU0nDuQsE95ITKwualIwEi0j0Pp1UpNMshiqbLdyDGs8lZczoplxK?= =?us-ascii?Q?GXSajzw4c0fXaPXQP6/v4JQt5zLzpdBD0q6XxH4l9Vzm7+/WNW/h4fgc3eg6?= =?us-ascii?Q?SboG78IrVBUcA1PcTdP45LHwOqGoDma5hM/pbaGTdfimK/0DfzjKJtEidfNP?= =?us-ascii?Q?dtN96Mw9DopxyLKg4pXveUqVzFRpicMVVjOmuI3mSUizjCvWYTjbZrslv+Uk?= =?us-ascii?Q?zuw1Li/6geHLWahKpbiYIdrKekH7l3QL4t3sLEdrMi2pAUemCx1cNGkbGrVm?= =?us-ascii?Q?EONVD2nmW5wbYLM9rO2/O7+U1FMwDZ87a0Hrqmn3EIw6MwVwZl6EXk/cyhEr?= =?us-ascii?Q?twEkWj/nXGBqeZMUudIH47IWKh+IRw/pCPnWjvDBX0TsJN+tA77xgWyzxegc?= =?us-ascii?Q?MJIrvb6gCUrwFw1+qO4ypEfq2Vz7yoHTu936tL7Ozw1ZZrGx6k+tQ+BfOZ7m?= =?us-ascii?Q?Btbc+ZdAipdcK2yuO9EGDIvuA2m3S+UOXwte9KsVPudgJIZnO1L9FoOQWckD?= =?us-ascii?Q?zEyPkMCpXtos+2Lgcgj7+4jqN4kIfSZ69lcBjE7V1H7x/Hm4Teopl6J6XImF?= =?us-ascii?Q?VZdk4nkgR8pIKvx2UJaXA0TDfbgCARRqnRH0YrPyv7sgCTP52fhdRYUZI8WF?= =?us-ascii?Q?pzAagvH1G3K057O4UGU22y1XrII/5MzbOvuXtejErTUE6TSsuFgShyZ9WT2t?= =?us-ascii?Q?b72b8nS6KIiets6mXjZB71nWZS1N1kmwGpdrfO?= X-Microsoft-Exchange-Diagnostics: 1;BLUPR03MB033;5:QrSJw0xKKSyfcDdkc/4JJkGIEFAb4209YzUUVHlN04jFFj2x0rkrw49rI3GTMZd3N84kGS8F9EpXYq2V92sTvjBB5tZJRMgOgvjxeBRSGsl3AseQV1udD4jjP1iyLFysM4qyHTF4MtaTp5OsbhhNOA==;24:IGGkYSlnarZWAeFEJhzXA4zZIfQ40mxbi3ZLKIAxAsXic6EsoZiUzoqDRyeGoG+fYVWkMiT7sG9wfb67yZxnOowH7aCBRvYWa146WOsR0c0=;20:oyJpGjz6GGjv8XJYXpMswOW/1icQBSUYc9XuNSbOdRg4ORvR8YthGae5OtXM0dF9uic6E5XTzPIHgkL1vbwsOmnoI/ie/lsva13l/5Zm1J/+i6P4uN4oPKaAgRGqRu94exOHYiOnPE8qdjtUbpuN91LxAx1zBqv442dlZ+N+YpM= X-OriginatorOrg: opensource.altera.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 27 Oct 2015 22:16:16.7724 (UTC) X-MS-Exchange-CrossTenant-Id: fbd72e03-d4a5-4110-adce-614d51f2077a X-MS-Exchange-CrossTenant-OriginalAttributedTenantConnectingIp: TenantId=fbd72e03-d4a5-4110-adce-614d51f2077a;Ip=[66.35.236.227];Helo=[sj-itexedge03.altera.priv.altera.com] X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem X-MS-Exchange-Transport-CrossTenantHeadersStamped: BLUPR03MB033 Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org From: Alan Tull Add a document spelling out usage of the simple fpga bus. Signed-off-by: Alan Tull --- v9: Initial version of this patch in patchset v10: s/fpga/FPGA/g improve formatting some rewriting move to staging/simple-fpga-bus v11: No change in this patch for v11 of the patch set v12: Moved out of staging Small changes due to using FPGA bridge framework and not representing the bridges as resets. --- Documentation/fpga/simple-fpga-bus.txt | 58 ++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 Documentation/fpga/simple-fpga-bus.txt diff --git a/Documentation/fpga/simple-fpga-bus.txt b/Documentation/fpga/simple-fpga-bus.txt new file mode 100644 index 0000000..bd43478 --- /dev/null +++ b/Documentation/fpga/simple-fpga-bus.txt @@ -0,0 +1,58 @@ +Simple FPGA Bus + +Alan Tull 2015 + +Overview +======== + +The simple FPGA bus adds device tree overlay support for FPGA's. Loading a +DT overlay will result in the FPGA getting an image loaded, its bridges will +be released, and the DT populated for nodes below the simple-fpga-bus. This +results in drivers getting probed for the hardware that just got added. This +is intended to support the FPGA usage where the FPGA has hardware that +requires drivers. Removing the overlay will result in the drivers getting +removed and the bridges being disabled. + +The simple FPGA bus will need to disable and enable bridges that will only +affect the child devices that are below the bus. If partial reconfiguration +is to be done, then bridges will need to be added within the FPGA design to +protect the rest of the bus when one part of the FPGA design is being +reconfigured. + + +Sequence +======== + +Load the DT overlay. One way to do that from user space is to use Pantelis' +DT-Overlay configfs interface. + +This causes the simple FPGA bus go be probed and will do the following: + 1. Disable the FPGA bridges. + 2. Call the FPGA manager core to program the FPGA. + 3. Release the FPGA bridges. + 4. Call of_platform_populate resulting in device drivers getting probed. + + +Requirements +============ + + 1. An FPGA image that has a hardware block or blocks that use drivers that are + supported in the kernel. + 2. A device tree overlay (example is in the simple-fpga-bus bindings document). + 3. A FPGA manager driver supporting writing the FPGA. + 4. FPGA bridge drivers. + +The DT overlay includes bindings (documented in bindings/simple-fpga-bus.txt) +that specify: + * Which FPGA manager to use. + * Which image file to load. + * Flags indicating whether this this image is for full reconfiguration or + partial. + * A list of FPGA bridges. + * Child nodes specifying the devices that will be added with appropriate + compatible strings, etc. + +Since this code uses the firmware interface to get the image and DT overlay, +they currently have to be files on the file system. It doesn't have to be that +way forever as DT bindings could be added to point to other sources for the +image. -- 1.7.9.5