Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1754751AbbLJXrR (ORCPT ); Thu, 10 Dec 2015 18:47:17 -0500 Received: from mail-bl2on0054.outbound.protection.outlook.com ([65.55.169.54]:43664 "EHLO na01-bl2-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1753531AbbLJXpU (ORCPT ); Thu, 10 Dec 2015 18:45:20 -0500 Authentication-Results: spf=fail (sender IP is 66.35.236.236) 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: Rob Herring CC: Moritz Fischer , Josh Cartwright , , , , Pawel Moll , Mark Rutland , "Ian Campbell" , Kumar Gala , Jonathan Corbet , , , , , , , Alan Tull Subject: [PATCH v14 1/7] fpga: add usage documentation for fpga area Date: Thu, 10 Dec 2015 17:37:03 -0600 Message-ID: <1449790629-5517-2-git-send-email-atull@opensource.altera.com> X-Mailer: git-send-email 1.7.9.5 In-Reply-To: <1449790629-5517-1-git-send-email-atull@opensource.altera.com> References: <1449790629-5517-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: SN1PR0501CA0035.namprd05.prod.outlook.com (25.163.126.173) To BLUPR03MB1507.namprd03.prod.outlook.com (25.163.81.25) X-Microsoft-Exchange-Diagnostics-untrusted: 1;BLUPR03MB1507;2:pcoLR/jKUXC2TANKC03x9+xx1Y4aHq1FLbtb1H4fGZ7H2sFe9YQCyho6/KLdi14Lvf/At9wRLFAfE86eyyWhcmzsIhvSyr/kAySrhA97OOu8ui9TzdusrcM7NL86MXz6mdsxfariYtK8zgTDq5JOiw==;3:VoB+rkDGMT0xxwia9wjfkoS7O5REMY99BmvNuAjYh1cFHUyUV/t1ufyFT7b1Dd025RIUPsBbIlijcd5jHipLVXMHozroFc0ZK401pbFvcnusxnhJYdtKd+BFwfLqPqLM;25:RoiMGY6F3uJyZvm1IjB7eN7Vtx6Z86zlyl37ZRokJJUxPPi16z0PA5icXm3t0QV7HADmF+j4EpS4UfPYdPnYo6HHXTL19LVQjo01CIQnHexWdAhW+Sn08yKrNC0dyQCuo+CUATbkVy+t7CTA+mwD1i8evUBs8r9CSNeDUjbeebguAub17LIpDd54mTwdVAOMCJlZlkSiO8qtNYHSpdxZOxWfKDj3tk3auk29wul8JWxr+sGCsc9rCz1TTxsHPToR;20:57brTRaIfpfyuUjNypYY0fVn/62ONCy1ApsgA0Vzl8xq0ZQMuIirNopCbb6sjbFBp6Zo50RUEvImiu5o+rn1bEQMvr9YH7VuJIbxqysoKLCiat3x260BJ9vXiQME256RLzcJOa9PRsHFAzIZKJF8YKku0pl0eYMEtETdlw2VPFU= X-Microsoft-Antispam-Untrusted: UriScan:;BCL:0;PCL:0;RULEID:;SRVR:BLUPR03MB1507; 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)(520078)(8121501046)(5005006)(10201501046)(3002001);SRVR:BLUPR03MB1507;BCL:0;PCL:0;RULEID:;SRVR:BLUPR03MB1507;BCL:0;PCL:0;RULEID:(601004)(2401047)(520078)(8121501046)(5005006)(10201501046)(3002001);SRVR:BY2PR0301MB2071;BCL:0;PCL:0;RULEID:;SRVR:BY2PR0301MB2071; X-Microsoft-Exchange-Diagnostics-untrusted: 1;BLUPR03MB1507;4:S8DZaO0sdKTamjbjk5IBG4nNvuijUOdiDaYDmnEWJKuUoSB+sN/21Bb9eejn47PcSkuFYCzOaDrwikzNQsaQiDi1iB8SDx3fw+hJMVwQpVDMfBGtYCgv4kBMxMK81/iglugRqgUzGLREIhz9TKd8PwkNg9derRlLZr0G41mnBKc9+CgUb9OeOSKRILIvm6P31IlzB5V2lCFOAqmVHMSRyHYBLV5mM6/Eh7r2Kb773IPJRi+PDFOY7+ts9zOgU1BxTC5QSL1HNIqj6qXL96rkqq7+iL3aTHXtPP6MW6UyMoUbuTKdaON3YGgtfyKVcLL9S/zSBe/RtnvUAYyrrhJiSUPkLLVP91DYUKc9ACbQr28LxbtGk5nVHEh+3HpS0IVk3X5tNIsHhZfOxciyHr4Txd2i0sDK/8UfLt3Q3NGJOzhA0axY+8AHBN8EB4k76nYJo2Y4sp0VsLqovDuqidFicg== X-Forefront-PRVS: 078693968A X-Forefront-Antispam-Report-Untrusted: SFV:NSPM;SFS:(10009020)(6009001)(189002)(199003)(229853001)(105586002)(19580405001)(77096005)(19580395003)(3846002)(2950100001)(47776003)(5003940100001)(50466002)(189998001)(86152002)(5001960100002)(48376002)(69596002)(50226001)(107886002)(40100003)(122386002)(87976001)(50986999)(86362001)(92566002)(53416004)(81156007)(42186005)(97736004)(76176999)(106356001)(66066001)(33646002)(101416001)(110136002)(586003)(6116002)(4001430100002)(5008740100001)(5004730100002)(1096002)(7059030);DIR:OUT;SFP:1101;SCL:1;SRVR:BLUPR03MB1507;H:linuxheads99.altera.com;FPR:;SPF:None;PTR:InfoNoRecords;MX:1;A:0;LANG:en; X-Microsoft-Exchange-Diagnostics-untrusted: =?us-ascii?Q?1;BLUPR03MB1507;23:pyczRWWzGev/SwIWaLzh4aEnBvNR17EZfQjxeBnG7?= =?us-ascii?Q?+/r6FilvJHYxp65utFZirIKAYUoUSqkBqwuNvHBQfG/gJm70+wYImqKuUvjW?= =?us-ascii?Q?1ru292MqUqrPPAtQg2oOR3Dkn0FDztM3jEVU45Q+NTQR6BC3ohyJ8GmcQwP6?= =?us-ascii?Q?+m981CyST+jxULpu0oG/fzpe5CQqwutJkS3C1vd0yb5Bo6yj2bOm2ZReyIZl?= =?us-ascii?Q?Ee1z92yl7zTE0dpyDr/oCeL4sbkRUCmp8s4gHr/Gox0vHauhQ3iuBxeVg20X?= =?us-ascii?Q?n01Y9sGBEZt6Y4KaYo2mkqXPxZ7kqfFpUDU5Jojap8KIEiNpNQBU8jd1IYbK?= =?us-ascii?Q?qqmm96WvDJSqRRElyTUgUzU66pRiVN4+tAm8FtR5xNlCo+iBUrc6TRjLbJeZ?= =?us-ascii?Q?OqLUL93jnvTfiA3f9YCaUpGG+u+YK+dqurvONhiEoRv4u4Qqys0khvj7+WQv?= =?us-ascii?Q?TQF5aXABN0yidBzxnzTEu7ZyyUrEgfHVPR/73W5zGJfvawX7FXkHAe1G6B1Y?= =?us-ascii?Q?sIW16rBYIT5jeJSOtCZnZ01P8FdApHi9HEyTECGBl8XBGgBk0js3PpPR+glm?= =?us-ascii?Q?5WzUcd55Sbi6NeEm5tnDgiuF9VwQrZK83Q9OSjit1zygO2m31/K9gKylM0wD?= =?us-ascii?Q?OsdLfFpGCReAwa69QWbWJ8HLapvlpc63lRTuiJ1c+sQk7fHzD2ngf237a0Uo?= =?us-ascii?Q?QLEFMBgclmjHVg6YXr71F/8JeCpXr4C7E4ctWh6t3zqcLATsaDIvI1aX1Pdf?= =?us-ascii?Q?K6oUkJdiJSXb5Vpn2l6YUHiqmyOiixylSInTVHnttPVCitwpPyloBJFjssxB?= =?us-ascii?Q?+cKUGDY53OAxOgqZkkqRNq67dkh8oJfA3/H43/eLA8Ev/BrrhyXVUj/5GGPS?= =?us-ascii?Q?CMfl5IoDGPDz6qlfK+QJbNzj0iJrUuc9HtbieryofVO23UTFUF5bXvVpBTQh?= =?us-ascii?Q?nSg4of6E8+021PoavjWdPm2sPk6v1gkmOEkmzUj9Vd9MBAVCvmjt55GbLf0J?= =?us-ascii?Q?fT4Ztn5m4Iadpd2XYCfnl3Wa3MPgUd5Ay5LAgrOgEpA/FPARdGiIJxj4oHrr?= =?us-ascii?Q?QNLkFxbIz8RM/XddEl85FCRO8+x0lACAiye13kDqFkq7pQ/Vt4lYZ1YWNWvP?= =?us-ascii?Q?te3BFPK8VkKJLBOFJfQmWLNwCk2+U6C?= X-Microsoft-Exchange-Diagnostics-untrusted: 1;BLUPR03MB1507;5:8sFHmViCen9Zx2fiEQGXnCI5Xwxph8JuqTAixXd3D21BGqQYFQFXvt++UzgBW+i8Wy3+Ri4uvzGOy5L8HNy5VuFpwqrZTrYhtdM4vZuCZj6ZUgPBT7vwrUOnE7tSqBNO7CUI+toaMM9lMF9/vDlIBQ==;24:OgyvJDPtBIONHPkTBAnNsn1a54ZuXsJLfZhgPI2PHkjRv/v9ePNPrAm8G+Hd2XMMMfJLgxt911JlUiy9l5JV9veocQJBTlLvD2OgFep1FMk=;20:CCNoF9bF6I/ZMfcnPeDE3jFnK/cFzkvMzcSYOrZyrN1KaBm5VOQts10tb/Aerrln8gO4AklHs2kxWvRRcHB/uXMLapLDNZ4hcbHdnJvosApBq/AqFISWpdRsd65WuuDP+wLsruo4YFWXNCy7NnNmUNWywrVgeh+pThb0mSRXGZ0= SpamDiagnosticOutput: 1:23 SpamDiagnosticMetadata: NSPM X-MS-Exchange-Transport-CrossTenantHeadersStamped: BLUPR03MB1507 X-EOPAttributedMessage: 0 X-MS-Exchange-Transport-CrossTenantHeadersStripped: BN1BFFO11FD043.protection.gbl X-Microsoft-Exchange-Diagnostics: 1;BN1BFFO11FD043;1:YP0ID31JuMHFMFFj5jPmn8v+aYZmjv3MB+7WEA66YeVLhIlSCiH+FHADX+z4/LrFrv4HS+GtEXNcc52fAGdwUdWOHpZr1gVRNx5NYUKReQp1c4maAUsBDJj3f58aGyF/jngsmwstjHTRsUQScyy3gGDUsmSB+ud9QcOj3GMTIlT261TGJUcbDeZJjoyaRQpy0eXCGwk6WgVahcSz74bkjd5sXqQrl4ONCq+Dfmd9FLKiFtIV3lCGIfWA3DBUNaLfSDQEUasqQHtwAfmOqu+Fu3AqcnO3O23L2hP3EjMXbEsS0Ji7B9vOpE/vBobh6a4I7azJWlfZsJf1xVgThqx5oWSv1PFxePawG74tfNoTXBRF9m0MLLhmz7UCKeoqCtBL4IuvL0iPZ9pPtW0Czo1diB5y9i44Ttxfxu2iaoczCU73u7IFqweaz4Oou4pkEUqz X-Forefront-Antispam-Report: CIP:66.35.236.236;CTRY:US;IPV:NLI;EFV:NLI;SFV:NSPM;SFS:(10009020)(6009001)(2980300002)(1109001)(1110001)(339900001)(199003)(189002)(87936001)(85426001)(11100500001)(50986999)(5004730100002)(105606002)(229853001)(76176999)(106466001)(21840400001)(50226001)(122386002)(16796002)(5003940100001)(86152002)(86362001)(97736004)(4001430100002)(81156007)(92566002)(5001960100002)(66066001)(107886002)(33646002)(6070500001)(47776003)(189998001)(40100003)(19580395003)(2950100001)(19580405001)(1220700001)(50466002)(110136002)(3846002)(77096005)(53416004)(6806005)(5008740100001)(48376002)(1096002)(586003)(6116002)(7099028)(7059030);DIR:OUT;SFP:1101;SCL:1;SRVR:BY2PR0301MB2071;H:sj-itexedge04.altera.priv.altera.com;FPR:;SPF:Fail;PTR:InfoDomainNonexistent;A:0;MX:1;LANG:en; X-Microsoft-Exchange-Diagnostics: 1;BY2PR0301MB2071;2:8qxxohNJMt+cJd2CQ+vjMdfvdNRFgYQupNGnYlzDvXKrt++I3KWZC1L89f0Op88oqGNxoTkqj90mGbHQ0krww7r5hSv9/h91KltwTV6Jdn//yeGWr6GnGCm9i8RL2KEs4U3dN7V/pPMVO3BdZFBnpQ==;3:nl31uEAdtLbB3In7yorNYP4bL6y2WTPxX9jJpzFv93mMQxTGNwHD+a7x5BnVc/44M42FPyiGnD3vNTIVniQVG4WkV7n8QIa2f55eHEm9VO4mopVl6pLTzHD4xtsmcSDwGq4sbGvL4uABMsmwo6iJ7PtsDiulYLYxNg93ZVHpglD7drGiAN5lR5aksQzqf4tcyzwjGKUcYIRpqhkDS6jl8KJL6jnYIx7MA6t6KK5bwck=;25:kOVI49IOrQnwGTNoL6KrLcKG2yKR1Gj8W1PCaYD0K8nMAr5el8cW1jLzy+J+gGE2k57mzCTZ4+eTzhlSQRwDQLISN4LIJTk5B1WH8b38TWRov3/wpTIIbgu6a90qt73CtxvkYiiKKzBH8gx6o9HoWjG83menHL6FYPtZUs0drohj+0/XHBJFOqAxAuC5FwuhxH5Yn0HWP4w5/FWUp5nwMfL55FV0uFBeqwNfkIRX/uWHO4KM7stz7u6KPkKbSOa+;20:8nryTRWD/ZBNGVPWiWzNd6m91Be+wGg6PFINhY9CjG+H/tW7kd5X2d1z9A1dyZ10m6wegSv5Hpc4ThFmNt2oHKPc5iL6lUeNw4eayW652geX6xqtrWnxXlux97EI2v7eWRjdNSvI/M0W0Y1/Ds9xxtHR7citN4V6+TArzIBQFko= X-Microsoft-Antispam: UriScan:;BCL:0;PCL:0;RULEID:;SRVR:BY2PR0301MB2071; X-Microsoft-Exchange-Diagnostics: 1;BY2PR0301MB2071;4:u0fqJLH2LwlKeV6ZpGvypSEseyYWKzuSt6kHc5r9jnqjwUjqMgouNDlqYDvR9y+UQksnY38h16U2susAFOd5GaSvo4CptLK2ZK6sWi3v3gVVAHyE94AvaoZRRkQYsW6Tn4AR+HqIbKvXsVoERPN7stmMyl28DrIeqfpWAbWDaqmL9LSL4DAgfOKJDnmCYzDKGLaWrhTgdv3r3rAtYod3sW/sEZVkB9H2FGjVCXXcUNMdJt5hZpvEvHZUY2IXVeWKWw1LvTishdW/Pv8n/K6CiEPNuzV9xluPaEHMrNTpZ0dAt8tjIlr6SCFeGIlmc+mvz0Rq3LymEpHZU6lm34JmrnoFeigePN1sCF1a6LtnoNyfzSHVvobujWoKW1fh6IatnWwOI/yiCiDX3UOBgXf4zugmFIIWRm9mfXza5CdQ0Tr55hUwKpB8wTGHgLWcpHxA0/XCTP1YJmXssQpkpu2ZgA== X-Forefront-PRVS: 078693968A X-Microsoft-Exchange-Diagnostics: =?us-ascii?Q?1;BY2PR0301MB2071;23:k8vM8XYf4LREq5Ny5qtx5QUYv7ItWw2UJ6II/XX?= =?us-ascii?Q?XVGK1tvtXaVztJ8GBYBqbQdJ3cZ4ZNLXck6NN513za3SlReb2ZLemaY5gIoy?= =?us-ascii?Q?f6xu0PCViwA4KOpJvTIcyWLUWYWLt5eZqQ1aWpCTB2/VxWRU9CPWiid5FJ9p?= =?us-ascii?Q?PCetSLtnUdX0zGlbnglbXtv8XLIDeZ3H4NBaTKm8Nuy20Whr8pePeacrQQJk?= =?us-ascii?Q?loTaPcFvXH72MpWvCS3IP9mWExKFMY+w/C5A+NhvxlHxrelC8xcbKoEEe+QR?= =?us-ascii?Q?N2Kp/mwe5CQwXERSxMotZUZMIdr41Q/c1G2FSY576rGDmEV+3gvXeOQVhqgG?= =?us-ascii?Q?tmPpi21GbHmReIXZEjpIP74IEkqFH5155nJIX4/e0ofefNhNIHqgxxqoDxrW?= =?us-ascii?Q?Uab4FRi/UisE7F1D+jsi//hIIW1l1H/4ixH3j+448ZSjQ5Pp0ZsX1/MN+zvd?= =?us-ascii?Q?lFrZWNLlrXgH/fB1pFQhi94DM8j8VUaFn99bZenLJjjGK/AlKno/OvA2USZd?= =?us-ascii?Q?KkGigjqGwwPSuRciZA3F/3y4FcSLKHYzg9Q/H9Ma+rsX+QhDjZtAmFidlBot?= =?us-ascii?Q?R/GRNq+jbGpyrTmHAYX8/c+1WA3IcRb+i6V0U+X1dVyXn2sLmCZYBGzZ+RZJ?= =?us-ascii?Q?EtOYHWPgM+lwLWyIwPKr4uLLCVCinfxB7A0WEAp1XoUaX803vd4IlZo3Q0ZJ?= =?us-ascii?Q?+RwIL6gIJEtQ1jvqd75BzirXzIL9Kol2tZ9zLzt7uguePYg3H1zIkoKRlioy?= =?us-ascii?Q?J9NvMzRIsbfPEoqzbv2YEAiVBeFfIantslo0iCGfHbmYGeLZw+Z6Y9CLN8vU?= =?us-ascii?Q?s86VZqMecea8cYzk6UrKJGlGpToF+wAKny0i9c2xCcKb9/+9qQv+99SsL1ue?= =?us-ascii?Q?cxiQy4XPVakt4RnE3UQmLFtz0fPPltvciTCAfRxc4wPK+s/PSSUtrWEt+Tkp?= =?us-ascii?Q?ljmL8kjxRjFdudYm3zEewclbFfNcSpGaiRRm3m+UjT8R79ClGLCYAXDAdh7D?= =?us-ascii?Q?Arj9jbG9msE/yYnz/3As5wwDh5sF/gJbUS8KKPBMjQlT88Wf1+TOGXNn/w6C?= =?us-ascii?Q?nrqJogoU+VvyInITSnpAYiII0i7aeHVz+VsACwu2XNE9s4o6YisFrwnXbWnf?= =?us-ascii?Q?mXlYsIMXIOVPAmAFCkpt6D6wZJjcZDE3eSWdZHUX0zWdTlfsaKsHUCrhnASJ?= =?us-ascii?Q?dbU8GrAeeehikiTR9nq2oCh6N/UPvVopB+D4LgBkYaUI46XJ/OL0KiueQExU?= =?us-ascii?Q?S01mg12xCq/bnNQTb2S2fkezqO0IlUjFcnw8rRyiC6aT7y2ve0z5OGP584d1?= =?us-ascii?Q?5pC6bq5MZ7xVM6UmjHqIimZehUHyfJPUyECCd160H1D8e?= X-Microsoft-Exchange-Diagnostics: 1;BY2PR0301MB2071;5:nnoo9alJ/T5K+b3PgoEr/TDCBxXihT5bjtz9Oaq8q6i8eF6FBixCyY4ISvNZY7Zsm+AsGQVfRsGQRTuGnkfHLLM+rVguntJN86241sg3LrTq/D3LqF44W76wvkRY5hocMyaJTH/KtSIwiFt2ILIvvg==;24:esTfIZmaHzMly7lummpHi23RA6d9L+In1Xz+DL5toUY8Z0mUogvUeIkkXTaTmA33C9/7VPaDb1twgQs5QiX3BXt1tGcTDZobhO1ExzWJdNE=;20:YSbDPWQFq96i6tV1o6+pEsvIfY54EzltowJTfvwkWEdbQopZ9Fj5Y7l6w0ldrfPh14clh7UgajmqALm101V5qusLipOHQfvhAiBhRHYNlObooKFG7Od5bVI1NkEDNvL4Y8eGIq6Bx2y/qBFFOUH3RtxrW7ZArJ75an3qtlHjKQw= X-OriginatorOrg: opensource.altera.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 10 Dec 2015 23:45:16.2394 (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.236];Helo=[sj-itexedge04.altera.priv.altera.com] X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem X-MS-Exchange-Transport-CrossTenantHeadersStamped: BY2PR0301MB2071 Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 10988 Lines: 337 From: Alan Tull Add a document spelling out usage of the FPGA Area for reprogramming FPGA's under Device Tree control. 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. v13: Fix some nits v14: fpga-area instead of simple-fpga-bus --- Documentation/fpga/fpga-area.txt | 299 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 299 insertions(+) create mode 100644 Documentation/fpga/fpga-area.txt diff --git a/Documentation/fpga/fpga-area.txt b/Documentation/fpga/fpga-area.txt new file mode 100644 index 0000000..f031522 --- /dev/null +++ b/Documentation/fpga/fpga-area.txt @@ -0,0 +1,299 @@ +FPGA Area + +Alan Tull 2015 + +Overview +======== + +An FPGA Area details information about a section of an FPGA including the FPGA +image needed to program it and the hardware contained once it is programmed. + +Loading a Device Tree overlay which contains an FPGA Area will cause the +FPGA to be programmed and the children of the FPGA Area will get probed. + +There may be FPGA Bridges involved to prevent spurious data from going out onto +the processor bus during FPGA programming. If so, the FPGA Area will need to +disable and enable bridges that will only affect the child devices that are +below the FPGA Area. In the case of partial reconfiguration, bridges will +be required within the FPGA design such that the active sections of the +FPGA are on the bus while sections that are not programmed or being +reprogrammed at the moment are isolated. + +Removing the overlay will result in the child devices getting removed and the +bridges disabled. Note that in the case of partial reconfiguration the rest of +the FPGA continues to function as normal while this is happening. + +Below are more details on the structuring of the Device Tree for this. + +Terminology +=========== + +Full Reconfiguration + * The entire FPGA is reprogrammed. + +Partial Reconfiguration (PR) + * Part of the FPGA is reprogrammed while the rest of the FPGA is live and + active. Not all FPGA's support this. + +Associated Blocks +================= + +FPGA Manager Framework + * An FPGA Manager is a hardware block that programs an FPGA under the control + of a host processor. + * The FPGA Manager Framework provides drivers and functions to program an + FPGA. + +FPGA Bridge Framework + * Provides drivers and functions to control bridges that enable/disable + data to the FPGA. + * FPGA bridges should be disabled while the FPGA is being programmed to + prevent spurious data on the bus. + * FPGA bridges are not needed in implementations where the FPGA Manager + handles this. + +Device Tree +=========== + +For the purposes of this document, I'm dividing the Device Tree (DT) into two parts, +each with its own requirements. The two parts are: + * The live DT prior to the overlay being added + * The overlay containing an FPGA Area + +The live DT will contain: + * FPGA Manager + * FPGA Bridges as children of the FPGA Manager (optional, architecture specific) + +The live Device Tree must contain an FPGA Manager to handle programming the FPGA. +If FPGA Bridges need to be involved, they show up in the DT as direct children +of the FPGA Manager. During full reconfiguration, the FPGA Area will disable +any bridges that are direct children of the manager during full reconfiguration +and will re-enable them afterwards. + +The insertion point in the live tree will also need the "simple-bus" +compatibility string to enable populating the child nodes for the overlay. +That includes the nodes for the FPGA Manager and controlling FPGA Bridges +as explained below. + +The Device Tree Overlay will contain: + * "target-path" + The insertion point where the the contents of the overlay will go into the + live tree. + * "ranges" + * "firmware-name" + Specifies the name of the FPGA image file on the firmware search + path. The search path is described in the firmware class documentation. + * "partial-reconfig" + This binding is a boolean and should be present if partial reconfiguration + is to be done. + * child nodes corresponding to hardware that will be loaded in this + region of the FPGA. + +Supported use models +==================== + +Here's a list of the superset of supported use models. We may need to add +more. Some uses are specific to one FPGA or another. + + * No FPGA Bridges + In this case, the FPGA Manager which programs the FPGA also handles the + bridges and no FPGA Bridge devices are needed for full reconfiguration. + + The DT overlay will specify the FPGA Manager as the overlay target. + + * Full reconfiguration with bridges + In the case, there are several bridges between the processor and FPGA, + that need to be disabled during full reconfiguration. + The DT before the overlay is applied will have an FPGA Manager. The + immediate children of the manager will be the FPGA Bridges that need to be + disabled during FPGA programming. + + The DT overlay will specify one of those bridges as the overlay target, + typically the bridge that allows memory mapped register access ("the + controlling bridge"). + + * Partial reconfiguration with bridges in the FPGA + In this case, the FPGA can have more than one section that will be + reprogrammed separately. Other sections may be active on the bus while FPGA + is being programmed. To manage this, FPGA Bridges need to exist on the FPGA + that can freeze all the buses going to one FPGA area while the buses are + enabled for other sections. + +Controlling Bridge +================== + +It is possible that there are multiple FPGA Bridges connecting the processor +and FPGA. In a text based hierarchy, it is difficult to show this properly +so what we do is consider the bridge that handles register access to be +the controlling bridge. The overlay is targeted to be inserted under the +controlling bridge. Other bridges are on the same level of the device tree +as the controlling bridge, i.e. all are children of the FPGA Manager. The +ranges property handles mapping memory ranges through multiple bridges. + +Sequence +======== + +Load the DT overlay. One way to do that from user space is to use Pantelis +Antoniou's DT-Overlay configfs interface. In that case the sequence from +userspace is: + + $ mkdir /config/device-tree/overlays/1 + $ echo "some_overlay.dtb.o" > /config/device-tree/overlays/1/path + +This causes the FPGA Area to be probed and will do the following: + 1. Disable the FPGA bridges. + 2. Use the the FPGA manager core to program the FPGA. + 3. Enable the FPGA bridges. + 4. Call of_platform_populate resulting in device drivers getting probed. + +Removing the overlay is done by: + + $ rmdir /config/device-tree/overlays/1 + +This causes the child nodes to be removed and then the bridges are disabled. + +Device Tree Examples +==================== + +The intention of this section is to give some simple examples, focusing on +the placement of the elements detailed above in, especially: + * FPGA Managers + * FPGA Bridges in some cases + * FPGA Areas and associated properties + * simple-bus + * ranges + * target-path + +Please note the "simple-bus" compatible string added for FPGA Managers and for +FPGA Bridges where the overlay is targeted for insertion. This is required for +populating the child nodes. + +Device Tree Example: Partial Reconfiguration with no Bridges +============================================================ + +Live Device Tree contains: + fpgamgr@0 { + compatible = "altr,socfpga-a10-fpga-mgr", "simple-bus"; + clocks = <&l4_mp_clk>; + resets = <&rst FPGAMGR_RESET>; + reset-names = "fpgamgr"; + reg = <0xffd03000 0x1000 + 0xffcfe400 0x1000>; + + #address-cells = <0x1>; + #size-cells = <0x1>; + ranges; + }; + +DT Overlay contains: +/dts-v1/; +/plugin/; +/ { + fragment@0 { + target-path="/soc/fpgamgr@0"; /* targeted to the manager */ + __overlay__ { + #address-cells = <1>; + #size-cells = <1>; + + area@0 { + compatible = "fpga-area"; + + #address-cells = <1>; + #size-cells = <1>; + ranges = <0x10010 0xff210010 0x10>; + + firmware-name = "fit_pr_v1.rbf"; + partial-reconfig; + + gpio@0x100010010 { + compatible = "altr,pio-1.0"; + reg = <0x10010 0x10>; + altr,ngpio = <4>; + #gpio-cells = <0x2>; + gpio-controller; + }; + }; + }; + }; +}; + + +Device Tree Example: Full Reconfiguration with Bridges +====================================================== + +Live Device Tree contains: + fpgamgr@0 { + compatible = "altr,socfpga-fpga-mgr", "simple-bus"; + reg = <0xFF706000 0x1000 + 0xFFB90000 0x1000>; + interrupts = <0 175 4>; + + #address-cells = <0x1>; + #size-cells = <0x1>; + ranges; + + bridge@0 { + /* both the manager and the controlling bridge have + * the added simple-bus compatible to allow child + * devices to be populated. */ + compatible = "altr,socfpga-lwhps2fpga-bridge", + "simple-bus"; + resets = <&rst LWHPS2FPGA_RESET>; + reset-names = "lwhps2fpga"; + clocks = <&l4_main_clk>; + #address-cells = <0x1>; + #size-cells = <0x1>; + ranges; + }; + + bridge@1 { + /* In the case of full reconfiguration, both bridge@0 + * and bridge@1 will be disabled during FPGA + * programming and enabled afterwards. */ + compatible = "altr,socfpga-hps2fpga-bridge"; + resets = <&rst HPS2FPGA_RESET>; + reset-names = "hps2fpga"; + clocks = <&l4_main_clk>; + }; + }; + +DT Overlay contains: +/dts-v1/; +/plugin/; +/ { + fragment@0 { + target-path="/soc/fpgamgr@0/bridge@0"; /* controlling bridge */ + __overlay__ { + #address-cells = <1>; + #size-cells = <1>; + + area@0 { + compatible = "fpga-area"; + + #address-cells = <2>; + #size-cells = <1>; + /* Note that two ranges are mapped due to the + * two bridges. */ + ranges = <0 0x00000000 0xc0000000 0x00010000>, + <1 0x00020000 0xff220000 0x00000008>; + + firmware-name = "soc_system.rbf"; + + onchip_memory2_0: memory@000000000 { + device_type = "memory"; + compatible = "altr,onchipmem-15.1"; + reg = <0 0x00000000 0x00010000>; + }; + + jtag_uart: serial@0x100020000 { + compatible = "altr,juart-1.0"; + reg = <1 0x00020000 0x00000008>; + interrupt-parent = <&intc>; + interrupts = <0 42 4>; + clocks = <&osc2>; + }; + }; + }; + }; +}; + -- 1.7.9.5 -- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/