Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752238AbbGQQLb (ORCPT ); Fri, 17 Jul 2015 12:11:31 -0400 Received: from mail-by2on0074.outbound.protection.outlook.com ([207.46.100.74]:4016 "EHLO na01-by2-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1752085AbbGQQLZ (ORCPT ); Fri, 17 Jul 2015 12:11:25 -0400 X-Greylist: delayed 907 seconds by postgrey-1.27 at vger.kernel.org; Fri, 17 Jul 2015 12:11:25 EDT Authentication-Results: spf=fail (sender IP is 66.35.236.227) smtp.mailfrom=opensource.altera.com; vger.kernel.org; dkim=none (message not signed) header.d=none; Authentication-Results: linuxfoundation.org; dkim=none (message not signed) header.d=none; From: To: , , , , , CC: , , , , , , , , , , , , , , , , , , , , , , , , , , , , , Petr Cvek , , , , Alan Tull Subject: [PATCH v9 1/7] staging: usage documentation for FPGA manager core Date: Fri, 17 Jul 2015 10:51:11 -0500 Message-ID: <1437148277-5405-2-git-send-email-atull@opensource.altera.com> X-Mailer: git-send-email 1.7.9.5 In-Reply-To: <1437148277-5405-1-git-send-email-atull@opensource.altera.com> References: <1437148277-5405-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: DM2PR21CA0039.namprd21.prod.outlook.com (25.161.137.177) To CY1PR03MB1519.namprd03.prod.outlook.com (25.163.17.25) X-Microsoft-Exchange-Diagnostics-untrusted: 1;CY1PR03MB1519;2:5Rzv99vc8tCQMvcG6tTI7/vZBaGomsRo+AztgQ123l4LAX10IkYKbJxNq/DHtRsA;3:GqTAhMVvRdnM5sr9XfNxuary9BP87ISgLdizF51HKegZAZ9kFqOv0vz/uuN2OYUibhHrxPQ9uLDf5kMgUImtFRG9gBN54n87bmUZw6lZYDA4YmewfBSAHg+ik9m9aKvaHFhL4QdLTyRkhK0elUCCFQ==;25:K9mAxYQe0HoP3Nmpi2mGcihr2a5BWT8BQMQSfVZvTZ/SrDEojw2BCWRdioalsaBxDKHhpVUKmI7k9zgsGQrGnU+u8V8bm3JOK0eFxb65nW2hGJx7zabkf4kJSPh7OvKGGEnuV+BsFz8shDVwwe7pfsrYfHwCaKJxSbQQfpOR8ujqXsA6qmjwYsxQyrMna6sCmUon6N3rFlmVI3+8xB/J0oLqEsYwXL4d+EpVnB6YxcGxwCk3uQwYWbUK/6SdZULkKCZavveI40toszmcoPTRGw==;20:gXt9A8rjTdQHyWxd3oU/A/5Gwgn52mRA4TqIKQ548QNQUw54WZog8IDT5RuEkqRGH9F89USBkNtu0bn4jpCmp/K83ylwrAm65ZJ+Ha2UDwSjBr+0oe6CRTKZilQ1I6isouqckBZz1FAabnMtf4jin0Szdr0gDtzxQic6kGksH/E= X-Microsoft-Antispam: UriScan:;BCL:0;PCL:0;RULEID:;SRVR:CY1PR03MB1519;UriScan:;BCL:0;PCL:0;RULEID:;SRVR:BL2PR03MB113; CY1PR03MB1519: X-MS-Exchange-Organization-RulesExecuted X-Microsoft-Antispam-PRVS: X-Exchange-Antispam-Report-Test: UriScan:;UriScan:; X-Exchange-Antispam-Report-CFA-Test: BCL:0;PCL:0;RULEID:(601004)(5005006)(3002001);SRVR:CY1PR03MB1519;BCL:0;PCL:0;RULEID:;SRVR:CY1PR03MB1519;BCL:0;PCL:0;RULEID:(601004)(5005006)(3002001);SRVR:BL2PR03MB113;BCL:0;PCL:0;RULEID:;SRVR:BL2PR03MB113; X-Microsoft-Exchange-Diagnostics-untrusted: 1;CY1PR03MB1519;4:XebBncAKucK3ixiFEYdhaBQp04I+bCoWRcHONV7WYdMT0EtZLZ8P3r7ghmFKoj/4nzhxg+dLEJhi2jgNS0f2oCRL5j3pwWFlT/QxNGT/OoIsM+f1yxaLfDanBS15Pr5LhUyw8s3tIVBWVA5qBn8F6rI9fNmVRfRhj8FwldDCnimSBM9aAiP239aD5FrzTSXz7TOpBmHiLjg9x3/arO2jnFaRAiTH+A43L8SyX/rPLbVRX4G6GqNviBEcup5Wn8Q5TAPPohSAWvFYDE6YyQyRU+XiCpN6JXOctvsPr30CJs8= X-Forefront-PRVS: 06400060E1 X-Forefront-Antispam-Report-Untrusted: SFV:NSPM;SFS:(10009020)(6009001)(42186005)(19580405001)(19580395003)(229853001)(53416004)(46102003)(87976001)(122386002)(2201001)(86362001)(86152002)(33646002)(62966003)(50466002)(77156002)(92566002)(5001960100002)(2950100001)(48376002)(50226001)(107886002)(77096005)(5001770100001)(76176999)(47776003)(50986999)(5001920100001)(5003940100001)(189998001)(7059030)(4001430100001)(2101003);DIR:OUT;SFP:1101;SCL:1;SRVR:CY1PR03MB1519;H:linuxheads99.altera.com;FPR:;SPF:None;MLV:sfv;LANG:en; X-Microsoft-Exchange-Diagnostics-untrusted: 1;CY1PR03MB1519;23:8P2KreLXGSz9u77GA4XB2KpG1h03hsfT+x541GsD9TFWK7W0l89ng49yZSONPclOnQuqXmf0DjoFp/DjbR6HILkIyT8fN8Z/7edXiJvPn6YuVcKAHHDzzfXp2k4QuMD3KROThwa5o/WQc6Q5mStgQfOLAnAg2D6ZWPq7+bWhmBbYQeVoU993HYESyY7frlDsk77DicE4iFx8LFCudfEAqrNdEGNPZuR403uzItv8ZHDBA1LJqCFl8Ycbm29pJ9mEDjzK17262F1OeI+s+M6GFY8m/cVNZ3weyY9nUhGg+OfBeHqO4pSjl2d+KKv6xsJJYFBW8vlihuNlOL1acZzTHugk2TbuMHQ0gOK3pFH2R/QOr2gSkbHV9seSfb05m3VafLyd83GItq2D85a/qLMgk0aw4e3rEEspYcjvEyTmbFH38hfm07trHSngAC/oIYmu83bzatqqBJRQd0zD41o9aRodAFSvB+70XsRmTiJX155rzO+49frH3/7l/7edxnY3rGQ901ZKd22jquU2/OIOQ2xMZDTclWq3Udc/vZ/87RGdsFpdeez50LVLs/U23aBVwsimrdrQH7DatnUHiksH7ubzjMk8Ajl8kuoqphM+WFmuuaqMuDieWH1Vb9D77MkCcGhy0dTsAzNrKJjm2wpbofj6Ja48/68qOW194mp8ZHrRKGyT9hKb5UyHRlTNsnXomWjJXfARiRXhW0j1iPyyeyA81RMH/pVsuxBza8yICTIhf2TXUFnxrcbYrDLW0nV4vmYfjqnZvGoRaj7hOlxmuuftV+z6bDZk1ZWD8TgllN4xhVNmPMpYTJ23W98cvvBTCG2SiubeOIDcKXCHfiX0OQtFR0jkh27Q3ybtQK2vNHxwuk9c9I9yQM6Mpc1Ku1PX1+UXc+xul+7oOU+gZrIy49dLGPcCpiJi9VkfO7g6oZo= X-Microsoft-Exchange-Diagnostics-untrusted: 1;CY1PR03MB1519;5:1HLZq3YCxOrOTe2JJgCbVDp7J2PWi1B8lsWhzwBvKSajJICANdq6OYHBS8oxnR6A5HkBPg37qUDUEGils5g+lqojpvzyk67fTDcDLDXxph2gNy8Q3EKI+Rq0l2xgERFwMZujZ5cUfCQ9mv4t95svxA==;24:2wLtiKcOHbmweVj/HQaDi9VcaQamzV93jgtBXSxaUHkhsOoq0hh/b38ooy7Qu7y9/Dk+s1a5aUupsd5ivBD0qi8ceunJAafS6vLvZkaShcc=;20:pQp8y9bmsEFY7GKy63EoEpT0UjNGT3L8ycWg1ok4lAt86rPmM2hvhrr5APoCwDQQqNaXGpje/kRyyQ3JPD7tsrCiIcISsLbv1ZduGKR71mH4ywDyr/zXn3c6VHd2D9MryOZ0qbL3qw1ZP8sFBHarJqMD/cbyfsYt3N+0HTgwkEM= X-MS-Exchange-Transport-CrossTenantHeadersStamped: CY1PR03MB1519 X-EOPAttributedMessage: 0 X-MS-Exchange-Transport-CrossTenantHeadersStripped: BN1AFFO11FD040.protection.gbl X-Microsoft-Exchange-Diagnostics: 1;BN1AFFO11FD040;1:mGiBCuwBkCiWbjIYgYzuf/ym+vSj3kFPwpI1imr6+m2a+UtyJKTKyFvh3JyhRToliyckF1XzQ5DtH9+ssNuAKHoJHgn+iSncrlrNVb5Ex9U73+V8Lk2qrVf2KxOOfFZzQ/mzJwRFefhX7+99fMkwKsJISSwi6rppepkFiELW3JM6FT8eK3pKgI71XEJqjD6/DL12bYvux1obTRA8ci5Mzq9wzo5+LxvUKupnErxcNkPWYhC8/6j2sEQNorlqam21Fq+nsnWN0i5fFW6mfoas+EN70/INrdtDFmfABOtus+jbtyLQBryO0YpQ5R+A4pr9XyKWkBbuX03p3mHOTxMXjURsa2zqkqAu9O8RVSkX7lQoLAqELCmHOxOxammvC9y+lbGdf+9H3RPVFdHRIyWfCqDZMvaW/jAv0fTDqxq7cYTHl2vOWolU3aZUxVBAtI0h X-Forefront-Antispam-Report: CIP:66.35.236.227;CTRY:US;IPV:NLI;EFV:NLI;SFV:NSPM;SFS:(10009020)(6009001)(2980300002)(339900001)(189002)(199003)(122386002)(53416004)(87936001)(47776003)(86152002)(2201001)(5003940100001)(16796002)(85426001)(62966003)(77156002)(86362001)(6806004)(189998001)(229853001)(5001960100002)(107886002)(33646002)(92566002)(5001770100001)(19580405001)(19580395003)(46102003)(76176999)(50226001)(50986999)(2950100001)(106466001)(105606002)(48376002)(5001920100001)(50466002)(77096005)(7099028)(7059030)(4001430100001)(2101003);DIR:OUT;SFP:1101;SCL:1;SRVR:BL2PR03MB113;H:sj-itexedge03.altera.priv.altera.com;FPR:;SPF:Fail;MLV:sfv;MX:1;A:0;LANG:en; X-Microsoft-Exchange-Diagnostics: 1;BL2PR03MB113;2:+gS7Cs2SY12qigJAbiu0dMlvUp5ogjctfKOxptOmI5k6kvShs9xe1jLmdJL/5h2G;3:PWf+CX4Z9gLbM/xMYOiUqRm9ESwtrSDNvYdpRDfeeWUua1iNZsKjNaOJ9bd01o5TQnDaZh/8EzbcQtgx7LGeyk10qkwqP46lx3wsfZQjmPyKEYvaaxFMc+42yB3LdObGDJ+YeHmyW4fupVYnMsV5UV6UnFCXMZ//AzLlF1Vi9j7G3wmLhQmnK8ONDc+keBouK0Pzhc8OHNNkYqThl01xhZ+puQoe4pOJ3OdlQ4fEr2g=;25:PAaOD2Uw+d0DSgrlwWid1TSNwQldet2inf789kIntcihzdtCKi/mi6TqMJJFCH6TmWeek8X1bzIBzso3tp6SxyneGRrlb4G090UVv5wSVzG1fQ2PZuhgwRySMb1lrOOomcLK81I2xegXVkqCfC8YiIUIwNST1MvdtW4Fus3UVmXIO2W5G2+nJOuEV4g+vLVAsfRJeEvSPlrZP0EIdk2UyCBmyoaAoHOqgT0lMsTSubSMdFG9e8MMSfiZH23wjtwBc3Hf1QOOGzmZbnYYNgsHsA==;20:PXdvQ2aQH3jxwikM8f3rOOhf+iHKJrFIQMWMT60p6pXKgBFK7KE5aZ8/pHeRw5IiPBTTzGzCiC1ycUPIEA/zIg9IUi3HuqUkITZgBdV/3tlUl1zHd1dgdZyy1xBbswAEvOBBZuSPD8hEBI4anPAPaMKMx5y2RUomKqJ2A+NTHDE= BL2PR03MB113: X-MS-Exchange-Organization-RulesExecuted X-Microsoft-Exchange-Diagnostics: 1;BL2PR03MB113;4:9y6yCgH7j2AmP70F2qfUmybog/rz7ljm1AuUPwT8INmWHkoJWhjELaGccTlrDVa6Due94xZizWIvkAlP+ZShifGvVKS3sVT1pYIuCriuqwtds4TvPRLk21TTWyg9R+x7VuHMWwycMsYqA4Z7MC/SoM7phGViix8C963YjBNHJ14XWIgavYtkKUxJAAlWs3msxvsKyJnBbUCkc4/zXKH9ufLXHMmGx2n603fDVW1Ail3uij5GNQK6h2GfF4oeMKPQt8p0/4N6pF2+cnSWg/0amBoVFmYoktwFw8DynOr3Lio= X-Forefront-PRVS: 06400060E1 X-Microsoft-Exchange-Diagnostics: =?us-ascii?Q?1;BL2PR03MB113;23:FnpmlLtzM4SRhqsVvsdG0KJMVOLnJtVjzX/L5bd2iW?= =?us-ascii?Q?TevNvQyxBL/TuV1CGocpE/T+MVtK1elvgcsVWmSqFg7BkrJoKuLWfqevW/bP?= =?us-ascii?Q?D/A4lB0B/ai6ZhwubR+ozbQUyWxCLhFtDr5dX5wbfSqgvXwUDRG7Pwwz8qJU?= =?us-ascii?Q?xFMSEksGY1URrnUX2n+eOtsfkNQpdxfvHgLyTlQSsz5aVV3r8N9HYzFQQFb1?= =?us-ascii?Q?KvYXQwwDByaTNNgbag090S36/KH7+Nw9NyXkYaSddQUS1AVSTkoHDU1TbBVT?= =?us-ascii?Q?yomAf8+0bm79VeUWIf7rQXfmynCXMSU1k3Nmzl7ibc1KbJksPUJg/tDofQny?= =?us-ascii?Q?24522IdBtyohNnHLuNSrgo8yJomz+lbcNHmMRrVkF56Fqs3gFVIHh+w495e/?= =?us-ascii?Q?Ay9xhI6F0FvCp9miiWKOY4rYmg1ROhMGojH4are0YITCK7fNYHFlpoeauGfG?= =?us-ascii?Q?agmr6iuP7F0gjSj2iPCKjW8e9yhYE3XGCQjQjR/jd0M1p1XodolUUwyLm7RZ?= =?us-ascii?Q?rb9i3aIoXB+DGPg9T7IX0uzBl9k7klphqDA46A9PPxOidVTjBO4het8Pk2is?= =?us-ascii?Q?7pYoH6VNYysSfv3hMcQRTjppZRAiTLOJFZCxkHg5uxIaWD82Fp8I8lF1xUXP?= =?us-ascii?Q?fg6sTecwwG1rdwOUiuOMh32nNl3h9uEhAUCxsrFdofe8Y7uJGyqiuIbCMrwV?= =?us-ascii?Q?vdLn9CEGU5v2Sk8NDEbn9vbWGWihDRXIXxzyGxODTFzZen9236okvOikaiPA?= =?us-ascii?Q?ZsBHkz8k8fYC6OAZQ+5CFUcEbeeWWfzvtvAPrrfzVGKd86hGxnglorE3n9LG?= =?us-ascii?Q?1vTpbmB0JmH/r+AO7egnvS4IT2Mw2+NRlIswHTnh2rCmHt0Fy3tAI+gjY6Zk?= =?us-ascii?Q?DaMdwK8pvMKQEIKHr2NjYA/+vfZ0x9foD6wr1Wp4ItKU3tYk+LZ3C4JzED7Z?= =?us-ascii?Q?5n+zEqs4Bk4iD65efYteuw27DsgMcfc3sSk2mKpP46LJuIFGGmb+YA1vUdBD?= =?us-ascii?Q?JG5WTNPo3Cgq+c7t7185pUM7/HGw62g3uHFPak5CuxzTRgnk06mMvY67Js//?= =?us-ascii?Q?hPp87qkxhHL3Pt+GXIPYHNZnhsALfbylsC25uF60W5tv6O3w=3D=3D?= X-Microsoft-Exchange-Diagnostics: 1;BL2PR03MB113;5:jTcDKIY9l6Y6zYV+AVk5UkPjgbgHjLOj+/uGMJOObCd+RSWxIaWbl9aO1nIVvWshn2ZArfW18UCHp0o72C7BcK0enn2Q6HfFlDIMMDpw1oNOwF+4RJNyIinZAxxXyJxQAqtidrZVUJ78/jen92H05w==;24:Tbpx8Fl01SaIEEiNbKAAC4/AaAyasusCpCMFoX33TQh7x2n8unzoXeJRp4Wl3J4MotOS6bDoYrrH8j6tBhGnGndO7c83C2b7O2MnbM+XPWA=;20:QNLsw3v6JwnLQ/o2YyNBTatytY251jP2K+bOs1rbzU/npdXHUHxjH22Q+HdIAN8EKE74+Z0y4i5z17jagqS/56lB+07mRVF0C9RPukMarodev+ieMlNnzxxr1+t4hrFSEpqrV6h3fojwSK4tKiMfyOTaABeG4QG9qwSqnPeoqKM= X-OriginatorOrg: opensource.altera.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 17 Jul 2015 15:56:19.0523 (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: BL2PR03MB113 Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 4904 Lines: 141 From: Alan Tull Add a document on the new FPGA manager core. Signed-off-by: Alan Tull --- drivers/staging/fpga/Documentation/fpga-mgr.txt | 117 +++++++++++++++++++++++ 1 file changed, 117 insertions(+) create mode 100644 drivers/staging/fpga/Documentation/fpga-mgr.txt diff --git a/drivers/staging/fpga/Documentation/fpga-mgr.txt b/drivers/staging/fpga/Documentation/fpga-mgr.txt new file mode 100644 index 0000000..b5b6ed4 --- /dev/null +++ b/drivers/staging/fpga/Documentation/fpga-mgr.txt @@ -0,0 +1,117 @@ + FPGA Manager Core + + Alan Tull 2015 + + Overview + -------- +The FPGA manager core exports a set of functions for programming an image to a +FPGA. All manufacturor specifics are hidden away in a low level driver. The +API is manufacturor agnostic. Of course the FPGA image data itself is very +manufacturor specific but for our purposes it's just data in a buffer or file +or something. The FPGA manager core won't parse it or know anything about it. + + + Files + ----- +drivers/staging/fpga/fpga-mgr.c +include/linux/fpga/fpga-mgr.h + + + The API Functions + ---------------- +The API that is exported is currently 6 functions: + + int fpga_mgr_buf_load(struct fpga_manager *mgr, + u32 flags, + const char *buf, + size_t count); + +An FPGA image exists as a buffer in memory. Load it into the FPGA. The FPGA +ends up in operating mode or return a negative error code. + + int fpga_mgr_firmware_load(struct fpga_manager *mgr, + u32 flags, + const char *image_name); + +An FPGA image exists as a file that is on the firmware search path (see the +firmware class documentation). Load as above. + + struct fpga_manager *of_fpga_mgr_get(struct device_node *node); + +Given a DT node, get a reference to a fpga manager. + + void fpga_mgr_put(struct fpga_manager *mgr); + +Release the reference to the fpga manager. + + int fpga_mgr_register(struct device *dev, + const char *name, + const struct fpga_manager_ops *mops, + void *priv); + void fpga_mgr_unregister(struct device *dev); + +Register/unregister the lower level device specific driver. + + + How To Write an Image Buffer to a supported FPGA + ------------------------------------------------ +/* device node that specifies the fpga manager to use */ +struct device_node *mgr_node; + +/* FPGA image is in this buffer. count is size of buf. */ +char *buf; +int count; +int ret; + +struct fpga_manager *mgr = of_fpga_mgr_get(mgr_node); +ret = fpga_mgr_buf_load(mgr, flags, buf, count); +fpga_mgr_put(mgr); + + + How To Write an Image File to a supported FPGA + ------------------------------------------------ +/* device node that specifies the fpga manager to use */ +struct device_node *mgr_node; + +/* FPGA image is in this buffer. count is size of buf. */ +const char *path = "fpga-image-9.rbf" +int ret; + +struct fpga_manager *mgr = of_fpga_mgr_get(mgr_node); +ret = fpga_mgr_firmware_load(mgr, flags, path); +fpga_mgr_put(mgr); + + + How To Support a new FPGA device + -------------------------------- +To add another fpga manager, look at the bottom part of socfpga.c for an +example, starting with the declaration of socfpga_fpga_ops. + +static const struct fpga_manager_ops socfpga_fpga_ops = { + .write_init = socfpga_fpga_ops_configure_init, + .write = socfpga_fpga_ops_configure_write, + .write_complete = socfpga_fpga_ops_configure_complete, + .state = socfpga_fpga_ops_state, +}; + +You will want to create a platform driver that has a set of ops like that +and then register it with fpga_mgr_register in your probe function. Your +ops will implement whatever device specific register writes needed and +will return negative error codes if things don't go well. + +The programming seqence is: + 1. .write_init + 2. .write (may be called once or multiple times) + 3. .write_complete + +The .write_init function will prepare the FPGA to receive the image data. + +The .write function receives an image buffer or a chunk of the image and +writes it the FPGA. The buffer may arrive as one chunk or a bunck of +small chunks through this function being called multiple times. + +The .write_complete function is called after all the image has been written +to put the FPGA into operating mode. + +The .state function will read your hardware and return a code of type +"enum fpga_mgr_states". It doesn't result in a change in hardware state. -- 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/