From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1755512AbcBEVcD (ORCPT ); Fri, 5 Feb 2016 16:32:03 -0500 Received: from mail-bn1on0078.outbound.protection.outlook.com ([157.56.110.78]:2740 "EHLO na01-bn1-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1750925AbcBEVb4 (ORCPT ); Fri, 5 Feb 2016 16:31:56 -0500 Authentication-Results: spf=fail (sender IP is 66.35.236.227) smtp.mailfrom=opensource.altera.com; codeaurora.org; dkim=pass (signature was verified) header.d=altera.onmicrosoft.com;codeaurora.org; dmarc=none action=none header.from=opensource.altera.com; Authentication-Results: kernel.org; dkim=none (message not signed) header.d=none;kernel.org; dmarc=none action=none header.from=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 v16 1/6] fpga: add bindings document for fpga region Date: Fri, 5 Feb 2016 15:29:58 -0600 Message-ID: <1454707803-27947-2-git-send-email-atull@opensource.altera.com> X-Mailer: git-send-email 1.7.9.5 In-Reply-To: <1454707803-27947-1-git-send-email-atull@opensource.altera.com> References: <1454707803-27947-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: BLUPR01CA035.prod.exchangelabs.com (25.160.23.25) To BN3PR03MB1509.namprd03.prod.outlook.com (25.163.35.148) X-MS-Office365-Filtering-Correlation-Id: 41303f51-58b2-457f-f912-08d32e73c40e X-Microsoft-Exchange-Diagnostics-untrusted: 1;BN3PR03MB1509;2:RKunSzgLg/9JpvfAmI4u6GZczIMlUCg6zrulWX6cZUjczzP52kcr6Ch66KY+sM/j4P9oxeLXKqtTGbHfb8iOMno1LcD8JEI2bagOsr1ZCnmljayQCa6odhidZZBHyzeorwrDAOhscvT8ebIw/yPYpIETLLTWDcAXgROlOIb5pS+o8HJ7r1ezGgIFC3h54oxP;3:TJXfTu/bvbeTrIFsEpvOr4SFkox/JI+jakZLO3SSVPsQqYyjfMhVzZAeAO3YBxMUvmTLxI8xFDGSUOwSGLRqvI6/8jjTj1NNkJf3Bp5HSLr69+9I5xxqLYSulKtM81vZ;25:Mqo6Ter7LwiB5PuePwblpn8j7KDbF2HmBTVZMn9jn3SYL9Dyvj880+NOF227wP6odTxXyVY3XvljF9Dajqrl6+aqM0cCABiW0Yab2mWW+YD5f5aeebXMczTujQoiDIKv0aa0oFrFIiIdLzkK7JkghsYkYrzJwyRvqSbZgE1/I3OevZXU8CF6VUK1j0y/LuOLvqeEH7WT/yqrbiu9HmJizGwkCaBjMVvuMypAT4auj4rJcaJc+XGK0+0piqlVMELqtS66QsiUU14S2P6lN66ha91E5ra40vs9qFe+asvDtq4OpHZc+QXWrSb6DagCfzrf;20:k2W7hFf/un9f9kVe1DIXq18p2eN2ABFgtIOFve4Zn6NHCRhlziajcgs2uYbOAwAUaiQZ/Z1YVenfyKZ9cDdTc1LSt1KpWwR4+FGRBdLlRWijlpL5lIlFkY5sG+F0QfccomhQBYkjz5yfOkU73Xy2Clpt/r4/qTkfHwbrv7VojNg= X-Microsoft-Antispam-Untrusted: UriScan:;BCL:0;PCL:0;RULEID:;SRVR:BN3PR03MB1509; X-Microsoft-Antispam-PRVS: X-Exchange-Antispam-Report-Test: UriScan:(80048183373757);UriScan:(80048183373757); X-Exchange-Antispam-Report-CFA-Test: BCL:0;PCL:0;RULEID:(601004)(2401047)(5005006)(8121501046)(10201501046)(3002001);SRVR:BN3PR03MB1509;BCL:0;PCL:0;RULEID:;SRVR:BN3PR03MB1509;BCL:0;PCL:0;RULEID:(601004)(2401047)(13018025)(13023025)(13017025)(13015025)(8121501046)(13024025)(5005006)(3002001)(10201501046);SRVR:CY1PR03MB1520;BCL:0;PCL:0;RULEID:;SRVR:CY1PR03MB1520; X-Microsoft-Exchange-Diagnostics-untrusted: 1;BN3PR03MB1509;4:ymNqrzjM2bmRlwQaBR6ckb841cIX/4tfrBIY6++8fB49kbiUeJimyTWFFbbuM78v55lsS+H433L4VVtW2YVy4pPmtlCITnFeqn7QU8ghAx02FoVkJsa3iFlwyG75RGLjf349i4gxpwuAA/pxjC3W6upP3cUmUCTUifFL+5ZvfUlZbHIUEeSMZRehO/msCENQzxpaZIzEq6T3oiUil5U9ZFK1tcFfSqqx551wqGm8aseQSWDJXxWNSYilJJiDSo0U7mwBdBq3yzQqQhZQ20z4t5oCY7Z4XGEs3+DF7SQsE038xc6KInET9UpX7Pmov6Cg37XdHVxFtEQaoK/OclydGF6hc/cB+14jjUJgF3BBsP6vNOvFFNjKuInSyvFaq8oy7MMQp46YQTjzY2hGPyXLhwnlN9cKHNWvNUD0q0dpJRk= X-Forefront-PRVS: 0843C17679 X-Forefront-Antispam-Report-Untrusted: SFV:NSPM;SFS:(10009020)(6009001)(229853001)(5008740100001)(6116002)(586003)(2876002)(2906002)(7520500002)(5001960100002)(189998001)(87976001)(4326007)(4001430100002)(5003940100001)(1096002)(40100003)(2950100001)(50466002)(5001770100001)(86152002)(92566002)(107886002)(3846002)(5004730100002)(47776003)(77096005)(66066001)(15974865002)(50226001)(19580405001)(19580395003)(122386002)(76176999)(42186005)(33646002)(53416004)(86362001)(50986999)(7059030);DIR:OUT;SFP:1101;SCL:1;SRVR:BN3PR03MB1509;H:linuxheads99.altera.com;FPR:;SPF:None;MLV:sfv;LANG:en; X-Microsoft-Exchange-Diagnostics-untrusted: =?us-ascii?Q?1;BN3PR03MB1509;23:jVypJhUBp1rbvJIdxS/V64k80mDidIckK59B6tvW/?= =?us-ascii?Q?696UySMHYujM0ozWLT/huH+aLmADabeYv/BRNa/gDbScNPmUTmveFDbPudEe?= =?us-ascii?Q?qRD1F3TkU98DPegK3lj6dbNlIUWcF5GmEn9ltncRKed98ArtBctJzzfxnSgR?= =?us-ascii?Q?esFLDtRhEy2+qUyXNfDBy+3p3rPZaRhfU7R2lNuISUYecVfbRCVEjTHoKx28?= =?us-ascii?Q?2Hk2uBNm1O/uVnygQhxHhNiP3p6Sq4ZsmRhVrgDY9UBqcpN4Q8qQSsg3dqGd?= =?us-ascii?Q?MizeAUxQO70jPNoPKdfQt4KgZoIsHQWBKNIG2Bd4MDXoWS3CTjeBBbupaPMB?= =?us-ascii?Q?GwdMnSlRv58VlbVY+vpLhbS4rgRTbIybKY801/uNb4EgHdi8yJaYu9ics6uD?= =?us-ascii?Q?4x/u4GQ0Db/oGZ0Ll5wqQnzzsTaFcDDLMqSWt9dQjVDcK1GKlMHhtOIkdS64?= =?us-ascii?Q?9V7DY9CU+Mba8F1OJQHY8/CdxAhqggb4ANTWPxuNKc4jaucsUzPMGsHxLQYq?= =?us-ascii?Q?UFctqdB18gXuYBJ0PGGfejkfWiRE3zT7RoWbcgQNbLKJBoKm73C+Z4nWVnqM?= =?us-ascii?Q?pVYjlMd2vchm2t03jTjZMFSxvf0pJO6BP5MOlMqnxFifNr1gIEmu+gfTHFaU?= =?us-ascii?Q?nBQRxVFhojdIWsnQ/OzgQ5DC4NcmHYsbn0ltaWGDHgjG2/rYlcEaPmdFw0Ra?= =?us-ascii?Q?ig7sX7rKtw4omimUyCXz9ZK7g/ymqecBGLyOW1VXsYaKDOnfzQmHp4cU6i5y?= =?us-ascii?Q?8azoF8Rgv7TtNThJncJUBnIVaaRErwvB/Eh2okUT0IJOPPGQWpWaW9WIIpSM?= =?us-ascii?Q?aXrQtFxKJ/QZm8FExMKrc2Z2xnpgjJCitdDyXG0pYVGltYWAqZ5Sq33u+R9G?= =?us-ascii?Q?HMdI0sYg5J/RuU0OZ0u59aoQH3pY0GEMwH8wwDcI04yOBeTWGF0W72yzABc6?= =?us-ascii?Q?5phRE792rlRz5PAddxvs/TnqB5mp87NBqhe3guz6MZ809ED9EkcCg2sbGi1N?= =?us-ascii?Q?N6JUgXyW9MefT6j9F9jb5Hl4WrpBSszjyn/2LV9KdpR8dqUrDzx1rwsCI1Rs?= =?us-ascii?Q?bhqgGNjAyWBN5jFrnzCX5yoEQKo?= X-Microsoft-Exchange-Diagnostics-untrusted: 1;BN3PR03MB1509;5:yHf7uoGyWf+PRrR5rFwH3kq/L0XrqSTDIlnRrpTerxTr0/k1eJwZ/XD7fnqiR+Iap/3q6uHIFaZbF+ifc7GDsZdc8q27aPSD+aM/1SFG/QopCbmNDRigelCBJMEem5lZkT8IS808LLgM6e2MlSoc7A==;24:XB4IMEWeIABIHatHGIFnxGfQOHwDUgISQowE6Dg6VELZslLLsyJdoZlv8b2DClwWcmOI9lORLgK53hOVsFtI8XviBI/1UDS8LXl3yxeCe6s=;20:vrLSl44XttTGIEdTak77wQAtvHTtHlCkEJqzfuOFoftt4SgoEctpXEhGVTG8qtjkRFuw6Pc2I9i+wJ7VTBerdK3gLxYcd9kfaZvyLGfRuYd9M4vJDj0rC5AUpnkNBQE8Eoo/RD8x4JSANIfKqYionc2OorB1CyvCTWLzmLvCYak= SpamDiagnosticOutput: 1:23 SpamDiagnosticMetadata: NSPM X-MS-Exchange-Transport-CrossTenantHeadersStamped: BN3PR03MB1509 X-EOPAttributedMessage: 0 X-MS-Exchange-Transport-CrossTenantHeadersStripped: BN1AFFO11FD029.protection.gbl X-Microsoft-Exchange-Diagnostics: 1;BN1AFFO11FD029;1:xR9S49TEUmEphSFCT4FNZZsZdJ2vGlbsUlhxyK/rFd/wmYTxDPaq20P/t7GXiKRVbrmtG5B8Q0PjAN+LMZgdkK7OxctXt/985VA+dRdxuQVjvi9bvq5yKZ94Cr7atesO4Mj00aleYvjOYBeEaUUzRlM+EjoiUYkkktF2texB3w8Q/R6T3yGBO2jkOshVtQ4emjaBfDBOoFIWn/54yzb5/hDb5+UymR9gWXRJ9kgqdrImw7UEJV0CjYWERRqdZko1zLZ0BQbww2zCIpwwOU59AH0TzMQ7xFjaMwmNXfbeAiXUfxtVKqSrGCx9GsXqSvtQM//2MdbmwwOBL39j/KBuHfzOKxmQUKJW4fJAqDx4+GQUjWTOJCZYMgLqJ16f1G/6j1K6P8KABrc1gYIplPmGvXYglTj06DmuTndqbvl8P8szCYaczyTW39qlCx4RQU5KICGMcBRhneYJge2Efcewsw== X-Forefront-Antispam-Report: CIP:66.35.236.227;CTRY:US;IPV:NLI;EFV:NLI;SFV:NSPM;SFS:(10009020)(6009001)(2980300002)(1110001)(1109001)(339900001)(199003)(189002)(76176999)(7520500002)(4001430100002)(66066001)(19580405001)(50986999)(586003)(6116002)(122386002)(19580395003)(956001)(3846002)(5008740100001)(5004730100002)(106466001)(86362001)(1096002)(2950100001)(229853001)(6806005)(40100003)(47776003)(1220700001)(11100500001)(21840400001)(87936001)(86152002)(77096005)(33646002)(105606002)(2876002)(16796002)(4326007)(5003940100001)(2906002)(50226001)(5001770100001)(189998001)(85426001)(92566002)(50466002)(5001960100002)(107886002)(3720700001)(15974865002)(53416004)(7099028)(7059030);DIR:OUT;SFP:1101;SCL:1;SRVR:CY1PR03MB1520;H:sj-itexedge03.altera.priv.altera.com;FPR:;SPF:Fail;MLV:sfv;A:0;MX:1;LANG:en; X-Microsoft-Exchange-Diagnostics: 1;CY1PR03MB1520;2:q7JVpEVP9ZrpHjKdfu3krC/X60cuHkuzw7/GfTkVpL454wQQ10lZvn8jTZgVwdF6UvX3sQTgXKrZSr2Cadu6ml3768OTHc25R1EJX0f4MsGDZMRUDpnnturu9iCWX+KWXqSlwXV09IEnqyFgwT5+fuiTaMVFdSEoPkPSpw2EtHxnWZaLr+asq5PMAVjtaN06;3:RtfqMuJf7Yf3x0JHz4/ORdpQzlTbdySXmFaBG5YZp+D9zBfdxynrvTQslntX9vvCbq8maWe7a4Z2ZPmiUL4ukzzHSWhNSz6qzIzI+ijP45pdaln1WIElSQvQbclbgJFQz51y4CY521vwyz3gU4RfU82tb2LRsveM6CuvWbA4SUKHAClz+KbLSJ8/rZCTWMcy1N2CugZ2h0xYUVRwt8qM01j7nGsBiaIR1eibZq7bDFu3LwOeoKBGakr6B4ubeISR;25:uCPTeq4jpznL9awRUrbiHv8Eiict3QrVhsKgwmFCA0Q2z64dZFONeD6Sh490Cg9786i1jdUbZu5Yg6qmGGh/nHQ/xRGvXbLfvpKjcFVPmDjtMgYR6E/ev8pLfsUuElu/LjkAGg52qZbxlpwQkKXFr1+tFnQke6ANyallIRe0bH4TbPSIK0HzRdW3dwMkBafnbWwuccf5xDA9sZtRM0oXwRY+LS0ab/H9rwXl3naeMFcSWiV7EiFkyGcYZN/so0WhhPD5me3AhbFfsON8iLvl3e+Z7HWsyYfRXX6s8s8UE/MbsvxxJJ3ficJRp5X4SvtN;20:xXzR0l57vPEe31cEpQgTkf98hKocdJm/CmI3Wn4OyS4XYv1PxOZpomnmrAIqRaeKdGld82k+JMoQbgJxpyoVdEDeAkAgqzM99mEfsElVlR9Rxni/Ptx0NWJnKfYYnR9LUXR5gq/Kdw2lFh+dEY7bC8CUYV/8pVlORkyCqHPy+eM= X-DkimResult-Test: Passed X-Microsoft-Antispam: UriScan:;BCL:0;PCL:0;RULEID:(3001016);SRVR:CY1PR03MB1520; X-Microsoft-Exchange-Diagnostics: 1;CY1PR03MB1520;4:svFENu8FJxx3SS5G1lFKawAnGuR1KxETS6JXMsr4UZDmiazDHWqzGgYLAuNVdmoyt/EU2fscHmQRq/T2TJQTrDdy13kLIbC3RsZKdN4W6wfrP473TjqtpTMzMTr1tq7Xviz2RKzQAqvNpVJNv7U5xLenWm2c5pC/JXIcTRA0VZWq16YFA5/fy4dEVszsxHhqOSPMUPutNvlMPQUPqdzvtKVyDHRzI89IQZgwbxwvB3R2GuBqNaWWYXZpasd/4yemkSLXpNAFOq5cI213kEwpflFmbUS39Hb5CIhB4daCzAa8czuVi97l26Koc7KlXodxdFfpoRGtR/sPkWjes6sy8Knt2li+iJHvmhewMjZ5m2u8NIa0QB/AQWrpwCDnU/DXnyb6DCN+XYrdXT60BPG4iTjJHD+KoNh/RkGs9jxv6A2oFxZD0ps68vH0SUSzLewkIkxIf+TbhyPhxtcMkYbobC3Ueps9Y9lCt3vsbegEPqSXH0GDlcU7VVOXajujYtER X-Forefront-PRVS: 0843C17679 X-Microsoft-Exchange-Diagnostics: =?us-ascii?Q?1;CY1PR03MB1520;23:BqORlfmXwmXOj2WfFvVMyPFd4D8MH0pamZ/t2y4dE?= =?us-ascii?Q?g4++8nIOL9h3846sPn1l2FeDxFkAadpbz1oXkn+Sg3cu6ETbQOslNnVkXV2J?= =?us-ascii?Q?fY0p/gV/tu6EzXMGPcoqGij2E/HzUpmd5f1panSX91iUku5D378tRxEu+1la?= =?us-ascii?Q?apMO6TNItkGHijGsLXNFLbGBSvwzyozotphpFXSxQ2kOADrkDynZ+iQBKvNc?= =?us-ascii?Q?7wCzG5B9D53phsw3jur1oxmnJ+/BXHSnqAj2xiOIQSQOH4s83ZzzTBUrZWVA?= =?us-ascii?Q?ZqS7gvORtUIIo9zNmVHp8GRFoqvNh3ebiWST8eQB1Dn9uL3SEo9Fji5C7rzU?= =?us-ascii?Q?5KjAU28c4VjnUHAdP1r9dmfVysfwCe9DTrgBqX7dwABAoo/Yijt7cJlqkzMm?= =?us-ascii?Q?4PMg1Sks/wgz9hTWqgiTtxeCJMEaPDgGZCPywf8rsdHhgWaZ+xXONCBKUDWt?= =?us-ascii?Q?YzqVgOYgWo113VopEvCzFHRzU36Trey9FodwpLllh31GnaS0TwvlGf2b3lRf?= =?us-ascii?Q?DUfEMQ5yA5CTeY3q/Q5c15z7rRwECFmRZBHgn3+9W9IHrw3PK6yvCyai5hs1?= =?us-ascii?Q?S9Wex1BGQdHDWKSIwjJrao9YIHfhZ6sl0JGFc9FoBDF3Qejjy7Bf+9pbQ8C8?= =?us-ascii?Q?iv8TM/ZPXNg+KAvt4YSfk8c3Ye7Cwa0JVPUOXNGRKWOKaZQPLVtIRm2k7u13?= =?us-ascii?Q?rwYTwVCnoGrvm6vi5ylrHQ1kr0GiARNdvGerh3cQZXLjtcC8Xa1o45NsFHRj?= =?us-ascii?Q?sP42A3w2VyR0xEGWxUvjvhOoAWKsrPZRyjL2dp0Pdr6xTg6vanD1mirb52HZ?= =?us-ascii?Q?vzHX9sl/iGRCxK8il3kWfi3M/bxBHqrUM8hbkZiqWGK2AROGWTnVyHUHeW6h?= =?us-ascii?Q?Id9/JkF5ql1mDnVTSlQ2f4Io0W0Q0fwmwioNLpmA4PLpLSRCC14Ht1jEE/QQ?= =?us-ascii?Q?NojAG2mHHtQ8JMyxBYhm87st6stoRm67MI3CFFRJf7Ox2lZFq2Ubfx0Gpj/N?= =?us-ascii?Q?JeD4VVbUypWr5VPazEf+fjaTmW/epSeS02jOXvOgFbMmKYN8YDVLTDsMH8b2?= =?us-ascii?Q?l+ZMHw6FLsX6uXT28tLsANQMZbesBb1Wl7G13407xOnxlEI4Vf6+1uOBfjQ1?= =?us-ascii?Q?KFls4sYy8j13i2H0hx5tNLtJXNpJ3R7iU6xAu6Dkg3xGMUxNX5lNSNHqINsi?= =?us-ascii?Q?zN4LbJkt4IJtsfsvM7IbS60QOLvp2sBBPgWIKNV5KhEa0iGkZQDDeInpJ9Xy?= =?us-ascii?Q?gw9b6pJ/bz12N4WuD4i5DK2PfQW+qQ5Yp1uiUBXiO0XzlYiRPYOR/ImQOmAU?= =?us-ascii?Q?WnCLUTKM8mlue+1KmQTb8dpZWV0KGIYlAq/1fGFB3LCqoaGn9U3R0h83gAR1?= =?us-ascii?Q?ElvmxlNDku1hp7nG46RLe18/UAUv2CUuULyrtagHBNS5T7pCONwYseywgrXa?= =?us-ascii?Q?4U1/1PTmw=3D=3D?= X-Microsoft-Exchange-Diagnostics: 1;CY1PR03MB1520;5:SXrY2zFZ+SpDp+45hgEWCh/EGzdZbLw67s/S7ANLoMhkGHh63xnF3xis1bJkN8BX+u1itiS1v1SZSzp3gih7GDUB4vbgvByzH4rvqPrDsYObK0SVCrVZ6JfOW2ldDhEWo3AqPMDaZVk1SMO1I3r5fA==;24:PNjp+BUbl/xQf71OgpCO1Gvfd1Kj7xuPIeP9xBt58CEIGjz7G+SoqnKMpw1DSCCkHXtcFYfZ/5Vkte8l/z29PP01ahGMfZeTKt1b5vbFOjE=;20:hQOgF5fRTyUfaSt//NQmRQSeM/geD2tfr6QW284BQf72b7W2og2yL/+xOxsFRmgScqIpPvI+4i4eZTCyTObkCngNTvKd/C0YhOU0J7kdCbG+ohrA/Bb6zfvfRDAqkfVfYc12CTyUES9wYTstnSh/KcirVau4PaZJPgc3Tp8vz7U= X-OriginatorOrg: opensource.altera.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 05 Feb 2016 21:31:52.9968 (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: CY1PR03MB1520 Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org From: Alan Tull New bindings document for FPGA Region to support programming FPGA's under Device Tree control Signed-off-by: Alan Tull Signed-off-by: Moritz Fischer --- v9: initial version added to this patchset v10: s/fpga/FPGA/g replace DT overlay example with slightly more complicated example move to staging/simple-fpga-bus v11: No change in this patch for v11 of the patch set v12: Moved out of staging. Changed to use FPGA bridges framework instead of resets for bridges. v13: bridge@0xff20000 -> bridge@ff200000, etc Leave out directly talking about overlays Remove regs and clocks directly under simple-fpga-bus in example Use common "firmware-name" binding instead of "fpga-firmware" v14: Use firmware-name in bindings description Call it FPGA Area Remove bindings that specify FPGA Manager and FPGA Bridges v15: Cleanup as per Rob's comments Combine usage doc with bindings document Document as being Altera specific Additions and changes to add FPGA Bus v16: Reworked to document FPGA Regions rename altera-fpga-bus-fpga-area.txt -> fpga-region.txt Remove references that made it sound exclusive to Altera Remove altr, prefix from fpga-bus and fpga-area compatible strings Added Moritz' usage example with Xilinx Cleaned up unit addresses --- .../devicetree/bindings/fpga/fpga-region.txt | 348 ++++++++++++++++++++ 1 file changed, 348 insertions(+) create mode 100644 Documentation/devicetree/bindings/fpga/fpga-region.txt diff --git a/Documentation/devicetree/bindings/fpga/fpga-region.txt b/Documentation/devicetree/bindings/fpga/fpga-region.txt new file mode 100644 index 0000000..ccd7127 --- /dev/null +++ b/Documentation/devicetree/bindings/fpga/fpga-region.txt @@ -0,0 +1,348 @@ +FPGA Region Device Tree Binding + +Alan Tull 2016 + + CONTENTS + - Introduction + - Terminology + - Overview + - Constraints + - FPGA Region + - Supported Use Models + - Sequence + - Device Tree Examples + + +Introduction +============ + +FPGA Regions are introduced as a way to solve the problem of how to program an +FPGA under an operating system and have the new hardware show up in the device +tree. By adding these bindings to the Device Tree, a system can have the +information needed to program the FPGA and add the desired hardware, and also +the information about the devices to be added to the Device Tree once the +programming has succeeded. + + +Terminology +=========== + +Full Reconfiguration + * The entire FPGA is programmed. + +Partial Reconfiguration (PR) +Partial Reconfiguration Region (PRR) + * The FPGA is divided into regions. Each of these regions can be programmed + while the rest of the FPGA is not affected. Not all FPGA's support this. + * PRR's may vary in size and in the connections at their edge. The image + that is loaded into a PRR must fit and must use a subset of the region's + connections. + +Base image + * An FPGA image that is designed to do full reconfiguration of the FPGA. + * A base image may set up a set of regions to allow for partial + reconfiguration. + +Persona + * An FPGA image that is designed to be loaded into a PRR. There may be + any number of personas designed to fit into a PRR, but only one at at time + may be loaded. + * A persona may create more regions. + +FPGA Manager & 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 may not be needed in implementations where the FPGA Manager + handles this. + +Freeze Blocks + * Freeze Blocks function as FPGA Bridges within the FPGA fabric. In the case + of PR, the buses from the processor are split within the FPGA. Each PR + region gets its own split of the buses, protected by an independently + controlled Freeze Block. Several busses may be connected to a single + PR region; a Freeze Block controls the traffic of all these busses + together. + + +Overview +======== + +This binding introduces the FPGA Region. + +An FPGA Region references the devices needed to be able to program an FPGA +device. The base FPGA Region in the device tree is required to include a +property with a phandle to an FPGA Manager. This region may also contain a +property that has a list of FPGA Bridge phandles, if needed. Child FPGA Regions +inherit the parent's FPGA Manager but specify their own bridges. + +The base FPGA Region supports full reconfiguration of the FPGA device. If the +FPGA image loaded contains the logic that creates a set of Partial +Reconfiguration Regions, then the DT that programs the FPGA should also add a +set of FPGA Regions as children of the original FPGA Region. +The child FPGA Regions do not require specifying an FPGA Manager as they will +use the ancestor region's FPGA Manager. + +The FPGA Manager is the hardware block that handles programming the FPGA. FPGA +Bridges function to prevent spurious data from the FPGA going on the processor +busses during FPGA programming. In the case of partial reconfiguration, +additional bridges (Freeze Blocks) for each reconfiguration region are required. + +The intended use is that device tree overlays can be used to add hardware to an +FPGA while an operating system is running. In that case, the live device tree +will contain an FPGA Manager, (possibly) FPGA Bridges, and the base FPGA Region. +The device tree overlays contain the name of the FPGA image file to be +programmed and the child devices that will be contained in the FPGA after +programming. Applying such an overlay will cause the FPGA to be programmed and +the child devices to be populated. Removing an overlay will cause the devices +to be removed from the device tree and free up those FPGA resources. + + +Constraints +=========== + +It is beyond the scope of this document to fully describe all the FPGA design +constraints required to make partial reconfiguration work[1] [2], but a few +deserve quick mention. A partial reconfiguration FPGA image must have +boundary connections that line up with those the current programming of the +FPGA. Also, those during programming, those connections must be frozen. This +can be achieved by "Freeze Blocks" which are FPGA Bridges that exist on the FPGA +fabric prior to the partial reconfiguration. + + +FPGA Region +=========== + +An FPGA Region specifies the devices needed to reconfigure a FPGA device. + +Required properties: +- compatible : should contain "fpga-region" +- fpga-mgr : should contain a phandle to an FPGA Manager. Child FPGA + Regions inherit this property from the parent, so it + should be left out for any child FPGA Regions. +- fpga-bridges : should contain a list of phandles to FPGA Bridges. This + property is optional if the FPGA Manager controls the + bridges during reprogramming. +- #address-cells, #size-cells, ranges: must be present to handle address space + mapping for children. + +Properties added in an overlay: +- firmware-name : should contain the name of an FPGA image file located on the + firmware search path. +- partial-reconfig : boolean property should be defined if partial + reconfiguration of the FPGA is to be done, otherwise full reconfiguration + is done. +- child nodes : devices in the FPGA after programming. + +In the example below, fpgamgr@ff706000 is used to program the FPGA. The two +bridges specified would be disabled during the programming and re-enabled +afterwards if the programming succeeds. The FPGA would be programmed with the +image contained in the "soc_system.rbf" specified in the overlay. Assuming +programming succeeds, the child devices would be populated afterwords. + +Example: +Base tree contains: + + fpgamgr0: fpgamgr@ff706000 { + compatible = "altr,socfpga-fpga-mgr"; + reg = <0xff706000 0x1000 + 0xffb90000 0x1000>; + interrupts = <0 175 4>; + }; + + bridge0: bridge@ff400000 { + compatible = "altr,socfpga-lwhps2fpga-bridge"; + reg = <0xff400000 0x100000>; + resets = <&rst LWHPS2FPGA_RESET>; + reset-names = "lwhps2fpga"; + clocks = <&l4_main_clk>; + }; + + bridge1: bridge@ff500000 { + compatible = "altr,socfpga-hps2fpga-bridge"; + reg = <0xff500000 0x10000>; + resets = <&rst HPS2FPGA_RESET>; + reset-names = "hps2fpga"; + clocks = <&l4_main_clk>; + }; + + base_fpga_region { + compatible = "fpga-region"; + fpga-mgr = <&fpgamgr0>; + fpga-bridges = <&bridge0>, <&bridge1>; + + #address-cells = <0x1>; + #size-cells = <0x1>; + ranges; + }; + +Overlay has: + +/dts-v1/; +/plugin/; +/ { + fragment@0 { + target-path = "/soc/base_fpga_region"; + #address-cells = <1>; + #size-cells = <1>; + __overlay__ { + #address-cells = <1>; + #size-cells = <1>; + ranges = <0x00020000 0xff220000 0x00000008>, + <0x00010040 0xff210040 0x00000020>; + + firmware-name = "soc_system.rbf"; + + jtag_uart: serial@20000 { + compatible = "altr,juart-1.0"; + reg = <0x00020000 0x00000008>; + interrupt-parent = <&intc>; + interrupts = <0 42 4>; + }; + + led_pio: gpio@10040 { + compatible = "altr,pio-1.0"; + reg = <0x00010040 0x00000020>; + altr,gpio-bank-width = <4>; + #gpio-cells = <2>; + gpio-controller; + }; + }; + }; +}; + +Supported Use Models +==================== + +Here's a list of supported use models. We may need to add more. Some uses are +specific to one FPGA device or another. + +In all cases the live DT must specify the FPGA Manager, FPGA Bridges (if any), +and a FPGA Region. The target of the Device Tree Overlay is the FPGA Region. + + * No FPGA Bridges + In this case, the FPGA Manager which programs the FPGA also handles the + bridges. No FPGA Bridge devices are needed for full reconfiguration. + + * Full reconfiguration with bridges + In this case, there are several bridges between the processor and FPGA that + need to be disabled during full reconfiguration. The live DT before the + overlay is applied will include the FPGA Manager, Bridges, and Region. + The FPGA Region will include the phandles of the FPGA Manager and Bridges. + + * Partial reconfiguration with bridges in the FPGA + In this case, the FPGA will have more than one PRR that will be programmed + separately. While one PRR is being programmed, other PRR's may be active + on the bus. To manage this, Freeze blocks need to exist on the FPGA + that can freeze all the buses going to one FPGA region while the buses are + enabled for other sections. + +Sequence +======== + +When a DT overlay is loaded, the FPGA Region will be notified 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. + +When the overlay is removed, the FPGA Region will be notified and will disable +the bridges and the child nodes will be removed. + +Device Tree Examples +==================== + +The intention of this section is to give some simple examples, focusing on +the placement of the elements detailed above, especially: + * FPGA Manager + * FPGA Bridges + * FPGA Region + * ranges + * target-path or target + +For the purposes of this section, I'm dividing the Device Tree into two parts, +each with its own requirements. The two parts are: + * The live DT prior to the overlay being added + * The DT overlay + +The live Device Tree must contain an FPGA Region, an FPGA Manager, and any FPGA +Bridges. The FPGA Region's "fpga-mgr" property specifies the manager by phandle +to handle programming the FPGA. If the FPGA Region is the child of another FPGA +Region, the parent's FPGA Manager is used. If FPGA Bridges need to be involved, +they are specified in the FPGA Region by the "fpga-bridges" property. During +FPGA programming, the FPGA Region will disable the bridges that are in its +"fpga-bridges" list and will re-enable them after FPGA programming has +succeeded. + +The Device Tree Overlay will contain: + * "target-path" or "target" + The insertion point where the the contents of the overlay will go into the + live tree. target-path is a full path, while target is a phandle. + * "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. + +Device Tree Example: Full Reconfiguration without Bridges +========================================================= + +Live Device Tree contains: + fpga_mgr0: fpgamgr@f8007000 { + compatible = "xlnx,zynq-devcfg-1.0"; + reg = <0xf8007000 0x100>; + interrupt-parent = <&intc>; + interrupts = <0 8 4>; + clocks = <&clkc 12>; + clock-names = "ref_clk"; + syscon = <&slcr>; + }; + + base_fpga_region { + compatible = "fpga-region"; + fpga-mgr = <&fpga_mgr0>; + #address-cells = <0x1>; + #size-cells = <0x1>; + ranges; + }; + +DT Overlay contains: +/dts-v1/; +/plugin/; +/ { +fragment@0 { + target = <&base_fpga_region>; + #address-cells = <1>; + #size-cells = <1>; + __overlay__ { + #address-cells = <1>; + #size-cells = <1>; + ranges; + + firmware-name = "zynq-gpio.bin"; + + gpio1: gpio@40000000 { + compatible = "xlnx,xps-gpio-1.00.a"; + reg = <0x40000000 0x10000>; + gpio-controller; + #gpio-cells = <0x2>; + xlnx,gpio-width= <0x6>; + }; + }; +}; + +-- +[1] www.altera.com/content/dam/altera-www/global/en_US/pdfs/literature/ug/ug_partrecon.pdf +[2] tspace.library.utoronto.ca/bitstream/1807/67932/1/Byma_Stuart_A_201411_MAS_thesis.pdf -- 1.7.9.5