From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752557AbcBYX2J (ORCPT ); Thu, 25 Feb 2016 18:28:09 -0500 Received: from mail-bn1bon0068.outbound.protection.outlook.com ([157.56.111.68]:19799 "EHLO na01-bn1-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1752280AbcBYX2F (ORCPT ); Thu, 25 Feb 2016 18:28:05 -0500 Authentication-Results: spf=fail (sender IP is 66.35.236.227) smtp.mailfrom=opensource.altera.com; lwn.net; dkim=pass (signature was verified) header.d=altera.onmicrosoft.com;lwn.net; 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: Alan Tull To: Rob Herring , CC: Moritz Fischer , , , , Pawel Moll , Mark Rutland , Ian Campbell , Kumar Gala , "Jonathan Corbet" , , , , , , Alan Tull Subject: [PATCH v17 1/6] fpga: add bindings document for fpga region Date: Thu, 25 Feb 2016 17:25:06 -0600 Message-ID: <1456442711-29138-2-git-send-email-atull@opensource.altera.com> X-Mailer: git-send-email 1.7.9.5 In-Reply-To: <1456442711-29138-1-git-send-email-atull@opensource.altera.com> References: <1456442711-29138-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: BLUPR01CA028.prod.exchangelabs.com (25.160.23.18) To BY1PR03MB1516.namprd03.prod.outlook.com (25.162.210.15) X-MS-Office365-Filtering-Correlation-Id: 03ffd2b6-7646-44fa-674a-08d33e3b48f0 X-Microsoft-Exchange-Diagnostics-untrusted: 1;BY1PR03MB1516;2:E1aZ9Mt2wepeFazZtNnNupL9bseiVS2iaLzQlw422JZRc6DCyrJdmVxXaVSLqgfk1gFT77IJJEpsQLTxmhCI+sbyIeEFIizlFycMPDYhMryyKnMLgrirHE6s6J+d3x7iyo1XzyMtKAOrvRxwKAnl53cBOebGWZdhb/uDgeRdVmRcfCWY4+glGr5AjAiSpAGx;3:uFbj6L5P4FpryX1weOSkoC/DwIneN/+Nvuf1opwPLm+l0dwLMTe8kr+PSTdq5LQ3kxuuRyQxe00KI+0/OgVycNQ9CdEuHFtGBF4joEt30/WVzYFx5OeFcIKjokgUItnG;25:/k5x/FpO5WiptH0hAEo+W3A5YFVglQx9QQ0h/uLnKX8nHORaYjeV+A8K4rqDyX0RBdVqz7BEQu3IezfzccWRZtIASwqcelvbD6zNZ/cOUvTbaJMx8JjUHsKHWqtagxZNIZx5twhutofrIZSOvmT6lEn7I7A46lEwClcGNJnd6lwh/qFc1cUlWyBdV1PBT9B1v3DVALtI4GzKgtCDD1BF+dcYM+yWbZ9DuwYgj/6Q4Pr2rV76rsLyj1v7GprXH9B9LfVKRlZ5zHQKHq6pp+SI0OS+UwmBIp84yBx2ZCZR7wWp8lM7XcaA9+JBnqSgUwD2SMhP2rUvvrgpzk1F35SDVQ==;20:CRzVFlHUqlshBhhAYyEJBIA3Jfb8GObv87oaMt9utgaZ9btf+t9NJOepBq6AtEqWFtbkcNpHVc9cO9Sl/0co+Ao/TluPqIIpxz71Rij0NdDG7VMXeg0n6eSJOF+UUdMrjAjKEc63pTIi01NByeliKUFz8QdcvTpyv5VsIaiIV4c= X-Microsoft-Antispam-Untrusted: UriScan:;BCL:0;PCL:0;RULEID:;SRVR:BY1PR03MB1516; X-Microsoft-Antispam-PRVS: X-Exchange-Antispam-Report-Test: UriScan:;UriScan:; X-Exchange-Antispam-Report-CFA-Test: BCL:0;PCL:0;RULEID:(601004)(2401047)(5005006)(8121501046)(10201501046)(3002001);SRVR:BY1PR03MB1516;BCL:0;PCL:0;RULEID:;SRVR:BY1PR03MB1516;BCL:0;PCL:0;RULEID:(601004)(2401047)(8121501046)(5005006)(13015025)(13018025)(13023025)(13024025)(13017025)(3002001)(10201501046);SRVR:BY1PR03MB1499;BCL:0;PCL:0;RULEID:;SRVR:BY1PR03MB1499; X-Microsoft-Exchange-Diagnostics-untrusted: 1;BY1PR03MB1516;4:tx0kcrOUUP2qe+fkobSVBb/sVpNNJR0Cd6R3OjUUdYzq+PbAJfaSgKalFher6gyTEnfImlvtjoFTJwhJLgQXWwDfuYMK6jqno1BIr9lE6Iec2lJ5gzefsf8k/YJBqCC0t+j1vcoLZ5g5TDhhjV6weDt9f0psRvMwZBtmWvH/ULiHPZ+YGxfCKXuGxJtSyRCmL0yBmWeSENJ32y+LKlcasi8Jg4Ol4aelk3trOKp22AlR1JyyxU85ePl29JnQAO1KjOFySnEBlFf6wM1ZGl+DbgWlbzCZrsYmKfm67T3KldIdcALRaiaZZMokyW6UOHRPaiJ3MeNsO3KawHllYW2iaxaQlJPUmONc+1SL6YzNN47LU6OC9gD0SR+DKWX24tzh X-Forefront-PRVS: 08635C03D4 X-Forefront-Antispam-Report-Untrusted: SFV:NSPM;SFS:(10009020)(4630300001)(6009001)(243025005)(50226001)(15974865002)(92566002)(48376002)(6116002)(15975445007)(229853001)(50466002)(19580395003)(19580405001)(33646002)(1096002)(77096005)(5001770100001)(40100003)(5003940100001)(2950100001)(122386002)(76176999)(2906002)(5004730100002)(5001960100002)(107886002)(42186005)(87976001)(50986999)(53416004)(3846002)(7520500002)(47776003)(4326007)(189998001)(5008740100001)(66066001)(4001430100002)(586003)(86362001)(7059030)(4720700001);DIR:OUT;SFP:1101;SCL:1;SRVR:BY1PR03MB1516;H:linuxheads99.altera.com;FPR:;SPF:None;MLV:sfv;LANG:en; X-Microsoft-Exchange-Diagnostics-untrusted: =?us-ascii?Q?1;BY1PR03MB1516;23:DV0BSJ3WYme39CfUFXEijcBSJDUiQ6KUfW8jDVIjX?= =?us-ascii?Q?aEo03e2CIcUUEaPS/FEgy4O7vxT+z1ZDJVa3nAaYOGMg+5Kk9GlE7MF7uxS6?= =?us-ascii?Q?cYVyYAbIra0cX4C0vWlhjrlNePDIqevbNBD0KxFeDrCtJDNpGl7VhC47yvSk?= =?us-ascii?Q?8b8p2qnHjR3/g7xX+NV7muox0Lt5r67JlHF3meygDusQe8Z29kBFUJk81loX?= =?us-ascii?Q?k/vPUY0wHI01izMubH1Tazt8WI5X9zsGvoto9AxlR4n0COSHXYNl3mewWPrj?= =?us-ascii?Q?ywYTbSw6X8u03MewPvoCklZY5Tq/Ek4JS0b3Al+KXURBct/C8yV06c6eC0t9?= =?us-ascii?Q?+VqDM/3yWykX0Si8rgMCtWHJ3zIvzeJL/9J4zYy8qYmt8LQPu1K1nbxsNnKR?= =?us-ascii?Q?5Ujr2s7/sek4JdRkfFA3PPo5Rh0dbevRv11zN+Bf8neQLSQbAjw4qiTvJ7oJ?= =?us-ascii?Q?v3GNS3gZG7yObqZ/DPHXwSafAiTYJ690TbdW+lvBbPWV9fmwwODYlBSKmaAp?= =?us-ascii?Q?NgrfMbrB6T3/BH4K/Ma9SyWi78hAUHCTTmVz/V9Jp9+KhWaKEh4+IezOSkj3?= =?us-ascii?Q?t1gXFAYk/sLi9WMI1PNVmx3u0SyMZ8c1NFheMgU/Zvw/fGpKl+9OCJvRWSHD?= =?us-ascii?Q?L7qKjhQ2a6TLYS+ergyTA6iPlLtu8UC7JOP7omr8RxfTbzXlGzN7lGvK42pg?= =?us-ascii?Q?bKMdJvEdZjIjWWUC9YiKEZcipNOnzPlN7DLOCzpdtYEAscQx7KvtdHiUxhr3?= =?us-ascii?Q?i60qWwBjHtXLSHbHwRCsCiTplrlCBCSRzcHrGFAyeOSxGoGGl5OCFV6fagUv?= =?us-ascii?Q?rPQxAcKp5U8Uj1YZGw3cMmfalJuRmZPyHnQSqOs0dT8gpt6TVr3YS0w0WpeE?= =?us-ascii?Q?1f1DfBZ1TbFGXwgYLJJD7sKKmBEyOXO2YRdIm5ZOpxHyqUyI0KFSzbRtsEfn?= =?us-ascii?Q?ysZx+819hiNeYiSnJYcTdNXjbnNAe07WBnoZTfEMtTCb+0QWWgUcuSxadvKY?= =?us-ascii?Q?iKFXgAi3WncQXSUYmQrI+KewYlb/5qdLR3+UZexv5vw52fQW72Z14TipwYX4?= =?us-ascii?Q?JtDEjtGGBKC6f4JWDRVv5cDrkxPW/dM6ve4Zuiqo6lYGtRT52ikRKfPd+CY8?= =?us-ascii?Q?2YWG9kJo1o1U7jlnheSnW+NyC9P4t9MNO1wAc9k4DTzPpcOLBd/EA=3D=3D?= X-Microsoft-Exchange-Diagnostics-untrusted: 1;BY1PR03MB1516;5:ynm04ETTcyHSqUE5be9S62SaZ/tG3WESfYqJuj6ggdV+rFpX7iqbThuijFCOE8FymlIDqvIGid+ABMp6qj1OJSZbdQ6MEbEkYymhAzgpTEskxhDsLd2crqolyeB48gpl70Ty06GnasCjQWuo58+TyQ==;24:ni1yQhc5rvUewAoGUQQmb93e0749CcXsOD5OUQNb1ADbcpA7JWcrl3yUt6q6JEqTj/0OLulPzfb4jIixW2A4h6nvZSldQC59RYY7dmgKy78=;20:ImymyWXnToNSIucOug6ijc7RO3UrUWTOhQWBEGhGnW92F1uzd4NXdFhfqjSB8t6f/X1+bKXT+6kd7Z9YyoRZUQMFQVLAEMoj6paRYbXs0XwYFy8CGYuwthYovzk5Bviou5pW+h9AwtRDeyLnOZ4+6NKPG7GDXB8Zu2L6w/MTlos= SpamDiagnosticOutput: 1:23 SpamDiagnosticMetadata: NSPM X-MS-Exchange-Transport-CrossTenantHeadersStamped: BY1PR03MB1516 X-EOPAttributedMessage: 0 X-MS-Exchange-Transport-CrossTenantHeadersStripped: BY2FFO11FD031.protection.gbl X-Forefront-Antispam-Report: CPI:66.35.236.227;IPV:NLI;CTRY:US;EFV:NLI;SFV:NSPM;SFS:(10009020)(6009001)(2980300002)(1109001)(1110001)(339900001)(199003)(243025005)(189002)(48376002)(11100500001)(92566002)(16796002)(3720700001)(3846002)(107886002)(6116002)(19580405001)(5001960100002)(956001)(50466002)(2906002)(4001430100002)(229853001)(19580395003)(76176999)(21840400001)(53416004)(50986999)(40100003)(5003940100001)(15975445007)(105606002)(122386002)(7520500002)(85426001)(77096005)(66066001)(1096002)(5008740100001)(4326007)(5001770100001)(15974865002)(33646002)(586003)(1220700001)(5004730100002)(50226001)(106466001)(2950100001)(47776003)(189998001)(87936001)(86362001)(6806005)(7099028)(7059030)(4720700001);DIR:OUT;SFP:1101;SCL:1;SRVR:BY1PR03MB1499;H:sj-itexedge03.altera.priv.altera.com;FPR:;SPF:Fail;MLV:sfv;A:0;MX:1;LANG:en; X-Microsoft-Exchange-Diagnostics: 1;BY2FFO11FD031;1:NEqH575HATKN40pl+HRyLVmD3tDYP2Q+aqQvKN4G3VUwIR2ZBHByUz96R+LqQcPyEpmeHTcnLIGFQSV5I8NlV+Hul0NReDYpsPHWh8x4PXeYtnVPGnPpGSmhxzNMSHIZToi72o0fXpCpKYR6yPXF/JxM12wu0/gRjuin8qQP8ov9O3DeeQxGu9I4hy+8toskAqMvS7/JuccOOdSE8FeyzyK5t+/QRxOrA6ZUW5f5JJa7f/Pi1s8k4hZxHGjpJRi98Qhps9ET9OAgd1aYMqtiasSx33c953en/Ae+sYCWAgHw0sSZHDc4hac+Q6IkzmIbw+uXeFE6fF+aiYpiuHSgPCOwwyzLEF+ocZ77fE+ZiUPSKhfkTxyMhFCgMTX1UR24UeMl3IqR8OZjSV3IoHPD+qETkXYQ2QHc2Xsgd3AmheH9J+kRLKtEg8aQMoWrgqPMAvN2Z8uthZxc+9zXmK2LpTi6SKNZ6yvlYPqDfGNVWZ4RJKfsrSWeojL9QQaaNVgq X-Microsoft-Exchange-Diagnostics: 1;BY1PR03MB1499;2:MCE6srMjkSCqaVsB7oLPnYMKr2Z3XzFYxPmecFMN0lFzI+SlKxreoY+c6ZIbaY45AS89XZ4k/BTj5Z8ENcUI0JRoplJsDG2tigoaSZK3zq5HJvJ/mpmzhhC64WcpeEHkpjfn/FQyoKoWuhBJU5b/bo2a+YUDwS0a6NCqPVDib13RJ06ft30MGbAtTCQKr5Pa;3:E4wDUB2ycqHrS/2EIcS7todeZhH62vfLpCgXtXlBtY/iaq0D5OLbpXhQO9EGDKmi6wnAWuzW4phkpIqg0kauC6JDzxO0snjtqWZA8gWgQFbefCil+F1mI8RUP7pB5nfhyP98HppgyUDPNehBKx32Kei9xePcFWHlse34/8DvRA0weylsbivorTMWuAAJ6h1a7sR+HAHcf7uf5Usr2PkRiQ==;25:9gEfPNWVpKb1eUbRQegiAKM3olMJH40gXdSB1IK1AKAoLY45bkOccuwKxAVDqBhLNct2SuxSv3YgbS4DgXSNFXSOHbvybsP9u7iEqFEQpxoqQj1flMRKS596OkHkjlnvTybyQBAwyuAyBNGuNOeDoGbMx/QmjJ4GTDt7XOtLtSpzuonfm9pmROMw/qkmwzBDuQOBTEM6evhT9CsFfwnW1ufOd3j62OfSx80RQ3UnJcfPtfT14FebcKvGz7oHDpi6GbrNx7jCKhlIJBf8J2OKrnDQ7Bjs8yi0humL1tgEcbD/Zp/ECd4TbmkyO3YilpYvYHFs1DSgkzNGCfxzDzpQAwRTlEKJpCh9i75bDcWVaMg=;20:zTdAIniZZnibum7bCh84lq+qdtbmocPl64Xly1hCkrWONIgvFe36XQssKEDEvGq9Ehu/KtGrRIfXMeuGpWAFll+7QeF1LC2oGnnzQ11tSjf7ICmDu169vLaXTm+cU71UmtQimUoZOv0UEeAYxLYPS4LNpU/hvuDUH+SMaMpaHoI= X-DkimResult-Test: Passed X-Microsoft-Antispam: UriScan:;BCL:0;PCL:0;RULEID:(3001016);SRVR:BY1PR03MB1499; X-Microsoft-Exchange-Diagnostics: 1;BY1PR03MB1499;4:exp7QxG68noneMM8Gni+llzvyGuO/VxivMWo8zas/TiE8wdcnTcSUv1S74F+7Md2yY6hxTQHF/N1u/vQoJ7hvrG+CDsdXpu7OH94jUnGWhwVq6dWVpRKaJfVCxAnZb83N+qaiv+580tMtEBdkqL94R+ZLwEWGl33Soi6u6mq91zsCElnii0jeAFFyjPvjo8iG9Qw3YLx6p5k4hSlWH4WtmMk8r8eXh40mriRcKa5FVql0je2K3xxjm5U7Rx4Hoctqctbi/w+j7XXU62XD2qv1PCQX7veT/R2kZZg56+BMRTKeUEUefZ6ECPSvWsMExqHy7eM1t8F34sntxqcrTAWQsknMbFNyipYWm4w4tcqWrMvQtpQJaFOmeQkx2TwSRRVdqq7VGluVXVeJ5sNHPhSWgSHfpATlAqwMbh7HaPn+a9JobvD1Gr09jLVQxPYv5nis37YQ5MxocYGb6khCszl/w== X-Forefront-PRVS: 08635C03D4 X-Microsoft-Exchange-Diagnostics: =?us-ascii?Q?1;BY1PR03MB1499;23:+mypIiKpozyauHMkMVv31s7ha0us2T/IkkIu9PXk6?= =?us-ascii?Q?+yIF9tZnVQ1idq15EhZazfwLmerPvs37l4jgM2gUGdnskfMGM0DHcH4GX36P?= =?us-ascii?Q?WrlPoITRIUcpzE4BX7uSAxo9yGh8UWJOriRFDxfsTQleGas4Qcm80IpwsnXd?= =?us-ascii?Q?8qksRWG2nHVlpTRk/W5RkIKXRzKUtCGEbPQ2CQMfoloIO2rdtT50hP+2gUm+?= =?us-ascii?Q?mB4dCeNNZX5Kf4w6uCOSduktFKoCv1r5IRrRCPA1A9S2gpcqJV1otfUCOvSN?= =?us-ascii?Q?39OuDMlHkH59p7phUoLflM8Xz4YA2Qa8TlGz7Yx+25K+TDdsnThTQ8IyJ3DH?= =?us-ascii?Q?bY56dFHT/wOL//W077oifsqtrIBVv84LrIii0qvbpNxuK5F9aGVgSKcbT/Yh?= =?us-ascii?Q?3KZSRNQnI/dyB1d2LXrTa8ZB6Npycm/n9AEV8MDwnKZc/jCYuTpT1CgT8nv7?= =?us-ascii?Q?N+64wPK/7A7YyAjJNM60ks+5V6UdzvgkIVg7CViok40fqtsQe/RuFJHzSQuN?= =?us-ascii?Q?O0RtRlTnCPrz2bfWvuvioeFUdXUcYjgKOPRwgGbiLk5nCegF9aMaTYz+QHQn?= =?us-ascii?Q?R4cEUch1Z+DiCTUqL1iQ+7367fh+W8s6DlFYCkHclKG/qOZKv36wrkh09Vm6?= =?us-ascii?Q?0B0msGiDXp1zPdxR35cXNnD/2tV7xbBX9IYnMAt/YnQEQgi2MlVCQkGUpsUX?= =?us-ascii?Q?enNdX7tBfZ8/aIfPntZfe1t6RUFtPrbhkSxx5F4gFHAIcTs9YeSeFQwxZhcv?= =?us-ascii?Q?dbrkiZtANG1HlCI18fXs1mgpU2pf+UJ/TrDL83vTvGHpj1am+axAUO18PbA2?= =?us-ascii?Q?qCo9v2P0YOLlCdb/F0po6F3w+uyi7ifVw+NbaoylvglJ0Laa7E9KS6Qx7S1U?= =?us-ascii?Q?UI2VuoJZkCABi++d1Tr78KtDSosCGHirylGCc+PRkVd7vJKm0qAPAAFQzm0I?= =?us-ascii?Q?hEAFtgHnLWA1zvlXjk6Er1Il51tNx2IumFxDntirOYP7PVF+pwim4sJpfs55?= =?us-ascii?Q?cq3PUwOXlEYL0eLVOG/enm/PglNOs+ya7rVrsxBayfi2p3gMUqyOnIS6MgBo?= =?us-ascii?Q?z5HLg7JrrqKzvHZI6HLyp5GXAXwYfuxKW0gZeMCVsNACwss8wPimPfPfShzr?= =?us-ascii?Q?WQ63m+/M6HehwpChQ8TE3mqkQPAe66kheZrjzWgvZoBmKLjgAqhp+kAzOGvR?= =?us-ascii?Q?juryBr8A2YLzmXSOM9gfoiDIbRFgci+7PxZwRmylbptOkSv9dW9yu75bVI4e?= =?us-ascii?Q?PhZWy0ZrCEG03EwQcPruVGWhM+PNQ7s6/1ZG+622b17A+1nmzhDjP4GbgOZb?= =?us-ascii?Q?NAHk+Hdnw8DYdIjZp3hFI3UCRY5psXEpazmqbNfSPqxBDOyjYVr222G3YoUg?= =?us-ascii?Q?WlpZlR57Tbxk0eWo4eOX3V4I4V0qf49FttpSGDcpgFy2C3khDsXsPUfD8DRW?= =?us-ascii?Q?/jcUL/Vd94HeEpIMHri3NkW8yBVsC42INApODteP2+pa8vYh/vP?= X-Microsoft-Exchange-Diagnostics: 1;BY1PR03MB1499;5:nhwxg56i/a7lY/pGN8xlUgE1bPythmb+Ns1sUrP2H9h+Q/mBL/jdzYfnZPYcpMXII6FeA6uDbJ3BqtUz1qcnMMmNMKySBWXn7cAqwAz0sF1+GOmb0IDdXLQaGwqz7lIzMYgJorbAcf9sh00F1UfUpQ==;24:QFgGWYPzdwAQ2zawKxv+FbNYPsKLPVut40INCBolUiPvGD8wsYB2MtEkU41TTBpX+6BZAy3epair4gojCqrFD/e+fv94DbzmKlVQLko6Q78=;20:JrbYlQ2sW7E760uHVFZIGTnJyGDknefwCo44/QqZNYLv6vTpF/GlqJRw9TBIAnB+A58yZmTwsrgsmYoph0Ns5BwFB4YNB/+BqNynhe+syQvK4NHYHfjbIfJJxpQjcMH34koG8D2HGvSn9Nf/FVTbS+yZgjYR2brmbibemsVNQMs= X-OriginatorOrg: opensource.altera.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 25 Feb 2016 23:27:44.5350 (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: BY1PR03MB1499 Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org 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 v17: Lots of rewrites to try to make things clearer Clarify that overlay can be rejected if FPGA isn't programmed Add external-fpga-config binding already used in u-boot Change partial-reconfig binding to partial-fpga-config to align with existing u-boot binding format *-fpga-config Add a document from Xilinx' website --- .../devicetree/bindings/fpga/fpga-region.txt | 491 ++++++++++++++++++++ 1 file changed, 491 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..141274f --- /dev/null +++ b/Documentation/devicetree/bindings/fpga/fpga-region.txt @@ -0,0 +1,491 @@ +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. + +This device tree binding document hits some of the high points of FPGA usage and +attempts to include terminology used by both major FPGA manufacturers. This +document isn't a replacement for any manufacturers white papers and +specifications for FPGA usage. + + +Terminology +=========== + +Full Reconfiguration + * The entire FPGA is programmed. + +Partial Reconfiguration (PR) + * A section of the FPGA is reprogrammed while the rest of the FPGA is not + affected. Not all FPGA's support this. + +Partial Reconfiguration Region (PRR) + * Also called a "reconfigurable partition" + * A PRR is a specific section of a FPGA reserved for reconfiguration. + * A base (or static) FPGA image may create a set of PRR's that later may + be independently reprogrammed many times. + * The size and specific location of each PRR is fixed. + * The connections at the edge of each PRR are fixed. The image that is loaded + into a PRR must fit and must use a subset of the region's connections. + * The busses within the FPGA are split such that each region gets its own + branch that may be gated independently. + +Persona + * Also called a "partial bit stream" + * 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 + * An FPGA Manager is a hardware block that programs an FPGA under the control + of a host processor. + + + ---------------- ------------------------------ + | Host CPU | | FPGA | + | | | | + | ----| | ------- -------- | + | | H | | |==>| FB0 |<==>| PRR0 | | + | | W | | | ------- -------- | + | | | | | | + | | B |<=====>|<==| ------- -------- | + | | R | | |==>| FB1 |<==>| PRR1 | | + | | I | | | ------- -------- | + | | D | | | | + | | G | | | ------- -------- | + | | E | | |==>| FB1 |<==>| PRR1 | | + | ----| | ------- -------- | + | | | | + ---------------- ------------------------------ + +Figure 1: An FPGA set up with a base image that created three regions. Each +region gets its own split of the busses that can be independently gated by an +soft logic bridge in the FPGA. The contents of each PRR can be reprogrammed +independently while the rest of the system continues to function. + +FPGA Bridge + * FPGA Bridges gate bus signals between a host and FPGA. + * FPGA Bridges should be disabled while the FPGA is being programmed to + prevent spurious signals on the cpu bus. + * FPGA bridges may be actual hardware or soft logic on the FPGA. + * During Full Reconfiguration, hardware bridges between the host and FPGA + will be disabled to prevent spurious data on the bus. + * These hardware FPGA Bridges may not be needed in implementations where the + FPGA Manager transparantly handles gating the buses. + * A base FPGA image may create a set of reprogrammable regions, each having + its own split of the busses that is gated by its own bridge in the FPGA. + * During Partial Reconfiguration of a specific region, the region's bridge + will be used to gate the busses. Traffic to other regions is not affected. + +Base Image + * Also called the "static image" + * An FPGA image that is designed to do full reconfiguration of the FPGA. + * A base image may set up a set of partial reconfiguration regions that may + later be reprogrammed. + + +Overview +======== + +This binding introduces the FPGA Region which supports full or partial +reconfiguration of a FPGA under device tree control. + +In the device tree, an FPGA Region brings together the devices (FPGA Managers +and FPGA Bridges) needed to be able to program an FPGA device. The FPGA Region +also includes child nodes that are the devices that exist in the FPGA. + +The base FPGA Region in the device tree is required to include a phandle to an +FPGA Manager. This region also contains a list of phandles to the hardware FPGA +Bridges, if any. This base FPGA Region corresponds to the whole FPGA and is +used for full reconfiguration. + +FPGA Regions that are children of the base FPGA region inherit the parent's FPGA +Manager but specify their own bridges. These child regions correspond to +partial reconfiguration regions in the FPGA. The bridges they specify will be +FPGA Bridges within the static image of the FPGA. + +The intended use is that device tree overlays can be used to reprogram an FPGA +while an operating system is running. In that case, the live device tree will +contain an FPGA Manager, 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. + +When such a device tree overlay is applied, it is targeted to one of the +existing FPGA regions. A few things must happen in the OS's implementation +before the overlay can be accepted into the live tree. The OS will attempt to +program the FPGA using the firmware that the overlay specifies. That +reprogramming sequence is detailed below (see the Sequence section). If +programming fails, the overlay is rejected. If programming succeeds, the +overlay is added into the live tree and correctly shows what firmware the FPGA +has been programmed with. Child nodes in the overlay are added and those +devices are populated. + +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 overlay 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 need to specify an FPGA Manager as they will use the ancestor +region's FPGA Manager. + + +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] [3], but a few +deserve quick mention. + +A persona must have boundary connections that line up with those of the partion +or region it is designed to go into. + +During programming, transactions through those connections must be stopped and +the connections must be held at a fixed logic level. This can be achieved by +FPGA Bridges that exist on the FPGA fabric prior to the partial reconfiguration. + +FPGA Region +=========== + +An FPGA Region specifies the devices (FPGA Manager and FPGA Bridges ) needed to +reconfigure a FPGA device. + +In the live Device Tree, an FPGA Region reflects the current configuration of +the device. If the live tree shows a "firmware-name" property under a FPGA +Region, the FPGA already has been programmed with that firmware. + +A device tree overlay that targets a FPGA Region and adds the "firmware-name" +property and child nodes is a request to reprogram the FPGA and, if successful, +add the child nodes. If reprogramming is not successful, the overlay must be +rejected and not added to the live tree. + +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. If this property shows up in a live device tree it + can only mean that the FPGA has already been programmed with this image. +- partial-fpga-config : boolean property should be defined if partial + reconfiguration of the FPGA is to be done, otherwise full reconfiguration + is done. +- external-fpga-config : boolean property should be defined if the FPGA + has already been configured. Then the FPGA Region can be used to add + child nodes for the devices that are in the FPGA. +- child nodes : devices in the FPGA after programming. + +In the example below, when an overlay is applied targeting base_fpga_region, +fpgamgr@ff706000 is used to program the FPGA and the bridge specified is +controlled during the programming. During programming, the bridges listed in +that region are disabled, the firmware specified in the overlay is loaded to the +FPGA using the FPGA manager specified in the region. If FPGA programming +succeeds, the bridges are reenabled and the overlay makes it into the live +device tree. The jtag_uart and led_pio child devices are then populated. If +FPGA programming fails, the bridges are left disabled and the overlay is +rejected. + +Example: +Base tree contains: + + fpga_mgr0: fpgamgr@ff706000 { + compatible = "altr,socfpga-fpga-mgr"; + reg = <0xff706000 0x1000 + 0xffb90000 0x4>; + interrupts = <0 175 4>; + }; + + fpga_bridge0: fpga_bridge@ff400000 { + compatible = "altr,socfpga-lwhps2fpga-bridge"; + reg = <0xff400000 0x100000>; + resets = <&rst LWHPS2FPGA_RESET>; + reset-names = "lwhps2fpga"; + clocks = <&l4_main_clk>; + }; + + base_fpga_region { + compatible = "fpga-region"; + fpga-mgr = <&fpga_mgr0>; + fpga-bridges = <&fpga_bridge0>; + + #address-cells = <0x1>; + #size-cells = <0x1>; + ranges = <0 0xff200000 0x100000>; + }; + +/dts-v1/ /plugin/; +/ { + fragment@0 { + target-path = "/soc/base_fpga_region"; + #address-cells = <1>; + #size-cells = <1>; + __overlay__ { + #address-cells = <1>; + #size-cells = <1>; + + firmware-name = "soc_system.rbf"; + + jtag_uart: serial@20000 { + compatible = "altr,juart-1.0"; + reg = <0x20000 0x8>; + interrupt-parent = <&intc>; + interrupts = <0 42 4>; + }; + + led_pio: gpio@10040 { + compatible = "altr,pio-1.0"; + reg = <0x10040 0x20>; + 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 hardware bridges between the processor and FPGA that + need to be disabled during full reconfiguration. Before the overlay is + applied, the live DT must include the FPGA Manager, FPGA Bridges, and a + base FPGA Region which contains phandles to 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, FPGA Bridges need to exist in the FPGA + that can gate the buses going to one FPGA region while the buses are + enabled for other sections. Before any partial reconfiguration can be + done, a base FPGA image must be loaded which includes PRR's with FPGA + bridges. This can be done by doing full reconfiguration using an overlay + that contains the FPGA image that sets up the regions in the FPGA fabric. + The overlay would also contain FPGA Regions that will become children of + the original base FPGA Region. + +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" + The address space mapping from processor to FPGA bus(ses). + * "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-fpga-config" + 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>; + + 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>; + }; + }; +}; + +Device Tree Example: Full Reconfiguration to add PRR's +====================================================== + +The Base FPGA Region is specified similar to the first example above. + +This example programs the FPGA to have two regions that can later be partially +configured. Each region has its own bridge in the FPGA fabric. + +DT Overlay contains: +/dts-v1/ /plugin/; +/ { + fragment@0 { + target-path = "/soc/base_fpga_region"; + #address-cells = <1>; + #size-cells = <1>; + __overlay__ { + #address-cells = <1>; + #size-cells = <1>; + + firmware-name = "base.rbf"; + + fpga_bridge1_0: fpga_bridge@4400 { + compatible = "altr,freeze-bridge"; + reg = <0x4400 0x10>; + }; + + fpga_bridge2_0: fpga_bridge@4420 { + compatible = "altr,freeze-bridge"; + reg = <0x4420 0x10>; + }; + + fpga_region1 { + compatible = "fpga-region"; + fpga-bridges = <&fpga_bridge1_0>; + #address-cells = <0x1>; + #size-cells = <0x1>; + ranges; + }; + + fpga_region2 { + compatible = "fpga-region"; + fpga-bridges = <&fpga_bridge2_0>; + #address-cells = <0x1>; + #size-cells = <0x1>; + ranges; + }; + }; + }; +}; + +Device Tree Example: Partial Reconfiguration +============================================ + +This example reprograms one of the PRR's set up in the previous example. + +The sequence that occurs when this overlay is similar to the above, the only +differences are that the FPGA is partially reconfigured due to the +"partial-fpga-config" boolean and the only bridge that is controlled during +programming is the FPGA based bridge of fpga_region1. + +/dts-v1/ /plugin/; +/ { + fragment@0 { + target-path = "/soc/base_fpga_region/fpga_region1"; + #address-cells = <1>; + #size-cells = <1>; + __overlay__ { + #address-cells = <1>; + #size-cells = <1>; + + firmware-name = "soc_image2.rbf"; + partial-fpga-config; + + gpio@10040 { + compatible = "altr,pio-1.0"; + reg = <0x10040 0x20>; + clocks = <0x2>; + altr,gpio-bank-width = <0x4>; + resetvalue = <0x0>; + #gpio-cells = <0x2>; + gpio-controller; + }; + }; + }; +}; + + +-- +[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 +[3] http://www.xilinx.com/support/documentation/sw_manuals/xilinx14_1/ug702.pdf -- 1.7.9.5