From mboxrd@z Thu Jan 1 00:00:00 1970 From: Subject: [PATCH v10 1/8] usage documentation for FPGA manager core Date: Thu, 13 Aug 2015 12:37:25 -0500 Message-ID: <1439487452-23977-3-git-send-email-atull@opensource.altera.com> References: <1439487452-23977-1-git-send-email-atull@opensource.altera.com> Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Return-path: In-Reply-To: <1439487452-23977-1-git-send-email-atull@opensource.altera.com> List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: driverdev-devel-bounces@linuxdriverproject.org Sender: "devel" To: gregkh@linuxfoundation.org, jgunthorpe@obsidianresearch.com, hpa@zytor.com, monstr@monstr.eu, michal.simek@xilinx.com, rdunlap@infradead.org Cc: mark.rutland@arm.com, linux-doc@vger.kernel.org, rubini@gnudd.com, pantelis.antoniou@konsulko.com, s.trumtrar@pengutronix.de, devel@driverdev.osuosl.org, sameo@linux.intel.com, nico@linaro.org, ijc+devicetree@hellion.org.uk, kyle.teske@ni.com, grant.likely@linaro.org, davidb@codeaurora.org, linus.walleij@linaro.org, cesarb@cesarb.net, devicetree@vger.kernel.org, jason@lakedaemon.net, pawel.moll@arm.com, iws@ovro.caltech.edu, Alan Tull , broonie@kernel.org, philip@balister.org, Petr Cvek , dinguyen@opensource.altera.com, pavel@denx.de, linux-kernel@vger.kernel.org, balbi@ti.com, delicious.quinoa@gmail.com, robh+dt@kernel.org, rob@landley.net, galak@codeaurora.org, akpm@linux-foundation.org, davem@davemloft.net, m.chehab@samsung.com List-Id: devicetree@vger.kernel.org From: Alan Tull Add a document on the new FPGA manager core. Signed-off-by: Alan Tull --- v9: initial version where this patch was added v10: requested cleanups to formatting and otherwise s/fpga/FPGA/g rewrite implementation section to not reference socfpga.c by name other rewrites Moved to Documentation/fpga/ --- Documentation/fpga/fpga-mgr.txt | 171 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 171 insertions(+) create mode 100644 Documentation/fpga/fpga-mgr.txt diff --git a/Documentation/fpga/fpga-mgr.txt b/Documentation/fpga/fpga-mgr.txt new file mode 100644 index 0000000..c5259e4 --- /dev/null +++ b/Documentation/fpga/fpga-mgr.txt @@ -0,0 +1,171 @@ +FPGA Manager Core + +Alan Tull 2015 + +Overview +======== + +The FPGA manager core exports a set of functions for programming an FPGA with +image. The API is manufacturer agnostic. All manufacturer specifics are +hidden away in a low level driver which registers a set of ops with the core. +The FPGA image data itself is very manufacturer specific, but for our purposes +it's just binary data. The FPGA manager core won't parse it. + + +API Functions: +============== + +To program the FPGA from a file or from a buffer: +------------------------------------------------- + + int fpga_mgr_buf_load(struct fpga_manager *mgr, u32 flags, + const char *buf, size_t count); + +Load the FPGA from an image which exists as a buffer in memory. + + int fpga_mgr_firmware_load(struct fpga_manager *mgr, u32 flags, + const char *image_name); + +Load the FPGA from an image which exists as a file. The image file must be on +the firmware search path (see the firmware class documentation). + +For both these functions, flags == 0 for normal full reconfiguration or +FPGA_MGR_PARTIAL_RECONFIG for partial reconfiguration. If successful, the FPGA +ends up in operating mode. Return 0 on success or a negative error code. + + +To get/put a reference to a FPGA manager: +----------------------------------------- + + struct fpga_manager *of_fpga_mgr_get(struct device_node *node); + + void fpga_mgr_put(struct fpga_manager *mgr); + +Given a DT node, get an exclusive reference to a FPGA manager or release +the reference. + + +To register or unregister the low level FPGA-specific driver: +------------------------------------------------------------- + + 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); + +Use of these two functions is described below in "How To Support a new FPGA +device." + + +How to write an image buffer to a supported FPGA +================================================ +/* Include to get the API */ +#include + +/* device node that specifies the FPGA manager to use */ +struct device_node *mgr_node = ... + +/* FPGA image is in this buffer. count is size of the buffer. */ +char *buf = ... +int count = ... + +/* flags indicates whether to do full or partial reconfiguration */ +int flags = 0; + +int ret; + +/* Get exclusive control of FPGA manager */ +struct fpga_manager *mgr = of_fpga_mgr_get(mgr_node); + +/* Load the buffer to the FPGA */ +ret = fpga_mgr_buf_load(mgr, flags, buf, count); + +/* Release the FPGA manager */ +fpga_mgr_put(mgr); + + +How to write an image file to a supported FPGA +============================================== +/* Include to get the API */ +#include + +/* device node that specifies the FPGA manager to use */ +struct device_node *mgr_node = ... + +/* FPGA image is in this file which is on the firmware search path */ +const char *path = "fpga-image-9.rbf" + +/* flags indicates whether to do full or partial reconfiguration */ +int flags = 0; + +int ret; + +/* Get exclusive control of FPGA manager */ +struct fpga_manager *mgr = of_fpga_mgr_get(mgr_node); + +/* Get the firmware image (path) and load it to the FPGA */ +ret = fpga_mgr_firmware_load(mgr, flags, path); + +/* Release the FPGA manager */ +fpga_mgr_put(mgr); + + +How to support a new FPGA device +================================ +To add another FPGA manager, write a driver that implements a set of ops. The +probe function calls fpga_mgr_register(), such as: + +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, +}; + +static int socfpga_fpga_probe(struct platform_device *pdev) +{ + struct device *dev = &pdev->dev; + struct socfpga_fpga_priv *priv; + int ret; + + priv = devm_kzalloc(dev, sizeof(*priv), GFP_KERNEL); + if (!priv) + return -ENOMEM; + + /* ... do ioremaps, get interrupts, etc. and save + them in priv... */ + + return fpga_mgr_register(dev, "Altera SOCFPGA FPGA Manager", + &socfpga_fpga_ops, priv); +} + +static int socfpga_fpga_remove(struct platform_device *pdev) +{ + fpga_mgr_unregister(&pdev->dev); + + return 0; +} + + +The ops will implement whatever device specific register writes are needed to +do the programming sequence for this particular FPGA. These ops return 0 for +success or negative error codes otherwise. + +The programming sequence 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 writes a buffer to the FPGA. The buffer may be contain the +whole FPGA image or may be a smaller chunk of an FPGA image. In the latter +case, this function is called multiple times for successive chunks. + +The .write_complete function is called after all the image has been written +to put the FPGA into operating mode. + +The ops include a .state function which will read the hardware FPGA manager and +return a code of type enum fpga_mgr_states. It doesn't result in a change in +hardware state. -- 1.7.9.5 From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1753362AbbHMRnS (ORCPT ); Thu, 13 Aug 2015 13:43:18 -0400 Received: from mail-by2on0084.outbound.protection.outlook.com ([207.46.100.84]:65344 "EHLO na01-by2-obe.outbound.protection.outlook.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1752824AbbHMRnH (ORCPT ); Thu, 13 Aug 2015 13:43:07 -0400 Authentication-Results: spf=fail (sender IP is 66.35.236.227) smtp.mailfrom=opensource.altera.com; ettus.com; dkim=none (message not signed) header.d=none; Authentication-Results: spf=none (sender IP is ) smtp.mailfrom=atull@opensource.altera.com; From: To: , , , , , CC: Moritz Fischer , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , Petr Cvek , , , Alan Tull Subject: [PATCH v10 1/8] usage documentation for FPGA manager core Date: Thu, 13 Aug 2015 12:37:25 -0500 Message-ID: <1439487452-23977-3-git-send-email-atull@opensource.altera.com> X-Mailer: git-send-email 1.7.9.5 In-Reply-To: <1439487452-23977-1-git-send-email-atull@opensource.altera.com> References: <1439487452-23977-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: CY1PR13CA0115.namprd13.prod.outlook.com (25.164.65.41) To BN3PR03MB1510.namprd03.prod.outlook.com (25.163.35.149) X-Microsoft-Exchange-Diagnostics-untrusted: 1;BN3PR03MB1510;2:wjqzocsZQAIJDwVKV6ClsDZqew9OMM01nvN97lo8zWFVH3B3ZYvzAyc4d6Z0/za8d9zx1gs41e+kvHTVldpgTkOW4C7RBpmjThTmSohF/v/utjTyzTTvyjuJDd1aGB9ihN9op1aiUKotH0vLAZd1v0WChM7BgjhZ5l3xH9qUGHA=;3:ZOMA8CDCXAXB+S1AinFm71MTKdrNGB39/2fmBfeXi4s9E8pcZ8gjjTuAAiJvusjWcb2sCH6Mtumj8kpgJQGUdgH9kbMePdj1FFf9DqgRV3WUef16SXieTxMFsybB/CLzhw1l1afGfjnG+YzCOA1X3w==;25:sQfRtUJ+V+tZ6MLz3pFmWMJe7gP5R+CaxAyQJymH/JBCeY7EpVI9484GSOK5arG6xMETCFRjgw6SqVuHlR9+NzH6rzRWp4XI+s13ojP0NySE79UUUrSHkZj37ywb6GwB72nErPwQIpnEcEgRaEjlfT4BtoDDJtDxCLtj1RuwMzCVC+C3FbzxYI/2dYBLOkBO+ALYBUNMe+11ewRrnv+54aEpoRCuZdK4qaXJqCOFx7Tuk43qazP8oLXy4a5jomlt1TVyz50X7FP8tueFha4HHw==;20:IZ3AZP66ZOTrkmE/ez7hzeBqwYbjCdgGbdNzgpeROYwqF+N1Pt2aeTyE4mFIoqOpCMlaYeffJ+tVnFcUyzq0eGivPmT14P+VecvpePunwhYyeznKE4/mxNzdTUyM1CkaRn4AnSivLQ37JPWGtgMrgNTOJdX3By45p/GHzGv5jm8= X-Microsoft-Antispam: UriScan:;BCL:0;PCL:0;RULEID:;SRVR:BN3PR03MB1510;UriScan:;BCL:0;PCL:0;RULEID:;SRVR:BLUPR03MB035; 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:BN3PR03MB1510;BCL:0;PCL:0;RULEID:;SRVR:BN3PR03MB1510;BCL:0;PCL:0;RULEID:(601004)(5005006)(3002001);SRVR:BLUPR03MB035;BCL:0;PCL:0;RULEID:;SRVR:BLUPR03MB035; X-Microsoft-Exchange-Diagnostics-untrusted: 1;BN3PR03MB1510;4:BCPs8U9eDK7MCM8FSmiTVpBxYesDWLIMw7sX1x9wmOBycrO9XQBRQTYKnzUWul1EJXJ3JdNXhcA5NKcD8ocB4DiT1kYPz1ApMFWt+vQHCQlMpTHbga9BKgXS75AXI1T4Mj23mpo05BDoPsx/z6sBB7tQu3Zioz5nF2lv7Aaib2lQSKI6r32yo51ITrB5ZHNdaSOC5XoxLw3DWi3iBEHcpZaYsgMhJZmTbWOWZZofAhuEm3dXxvpoGnzS7NjjpG4dECrR3pvRYTpM57BR17asNRjBMHWC/DuRSeswGLzJK34= X-Forefront-PRVS: 0667289FF8 X-Forefront-Antispam-Report-Untrusted: SFV:NSPM;SFS:(10009020)(6009001)(199003)(189002)(50986999)(86362001)(87976001)(48376002)(50466002)(77156002)(101416001)(2950100001)(76176999)(5003940100001)(122386002)(69596002)(53416004)(42186005)(62966003)(97736004)(40100003)(229853001)(189998001)(5001960100002)(81156007)(107886002)(50226001)(5001860100001)(86152002)(4001540100001)(64706001)(66066001)(2201001)(47776003)(5001920100001)(5001770100001)(46102003)(19580395003)(68736005)(33646002)(92566002)(77096005)(19580405001)(106356001)(105586002)(5001830100001)(7059030)(2101003)(4001430100001);DIR:OUT;SFP:1101;SCL:1;SRVR:BN3PR03MB1510;H:linuxheads99.altera.com;FPR:;SPF:None;PTR:InfoNoRecords;A:0;MX:1;LANG:en; X-Microsoft-Exchange-Diagnostics-untrusted: =?us-ascii?Q?1;BN3PR03MB1510;23:fySla47CKTu/NKcGUiP6ODqkSVyDqStInqZzKjv8J?= =?us-ascii?Q?204OZXr9sCuF6LRC92IjhB5MDRKwicpebA+Ljs2U4rbvopeEL5+ECJjhPkgx?= =?us-ascii?Q?If2Fr+BrB/+8LNDyZQsA1Cd3MAM2/VtGjUOVXWiVlaGzmfIFE8bR5fh53h4Y?= =?us-ascii?Q?N6AQp4EGK7Oi7nygbnZv0Z0fHzqRG3fR1w4UcnQfbxP0XlChZPk3VgDKhLAx?= =?us-ascii?Q?9RC4dX/Y8rdFWMJ9zzR7s3Huc0xALb8QB6eZTpS6F37ehKJaVVOGAQKDu69u?= =?us-ascii?Q?Bea5Y6sHky0pDsEc1KJc1PIhOAN0vb6/ZB+/Iz7YLmGNIp4ieqBDdhIcULea?= =?us-ascii?Q?sPf/HEniiMgQ14eeclFYy/ibBQP70GI49Vs+Tnn9yzOCga9+xE13QM4YsH3/?= =?us-ascii?Q?e05Q398gX2HvIpbFWHuZWmboUb9/zi7u908k45zK6fifCIWR7GO6pBvdTDwF?= =?us-ascii?Q?3xy/lOzg6bFk1MsmFYyp3Hh9mJ9Wqq2ODdM/zmb5cv6apemMmmBMSfiEm01V?= =?us-ascii?Q?2kynHE/FsV8ewNCHHv6KDo1rxqRe3XOSP6lLSZ0H8sWlQSfPIUVcNZIVMcYN?= =?us-ascii?Q?fMFMWwxaPogmcNcUM1/clz08ela7xcUVEsEC5K9lS/OElkZQZmwBbaTNuyof?= =?us-ascii?Q?8gwfuUCfPJUljQsH/l3aiHZWGAvcj4E9J7hnrJbfA9A7jQ45wTZBkQ8pMfP2?= =?us-ascii?Q?ZMVb2ZLaP2YotKqdRV04KQ0Pu2zcUg+FCyddt3hIjXEVEW6XnAwI2Is/rrA3?= =?us-ascii?Q?bcUp69wcuTQol97J3VdHTTPJz6JSFiE9sb2F4l590UcUchwRpgV/4q08PthO?= =?us-ascii?Q?L14hDfcRn6xDRdG24JQhUWQhtCc5Vc/vrLfGFvZomjAA+Fc5VdzGIiMDdJex?= =?us-ascii?Q?XByYFbkRxMa+lj0zVGbVQz+5JjcIWdEeKP89H7ulutGSBSuUhrmejVbc0Sk0?= =?us-ascii?Q?FPWkVX/Fa7IWNdl3RrmuNEa4G4SuFAxcNFDKhKF3gXcoRWDj4QBKywD3wXK/?= =?us-ascii?Q?fSMI+izPvu+FZZiXJ3eg85ySNbbm0zBHY7iMLSnp6lsJ72+qqXHwN4y8o5pl?= =?us-ascii?Q?Wo1eDxJjDFytPwKL4tDiLxC+QTvb3ixblg0GrI6YOWVTK/8b7sU2U3hnB4ta?= =?us-ascii?Q?ZqBwhE0/raRwQuCIhhAqF3iw10nxre4qbwovAi0hgBhMFLN4ec6inr/JMg9+?= =?us-ascii?Q?yNtISQKIXB4Z6Zd4JN46ZAtKs+I8K4oKOxrLOQiYXjB4fTQWyYs/ffewrk6a?= =?us-ascii?Q?RIyQBK6MidhrB/i6uIf0NLWvWXpxc5NmVVqW1Ic?= X-Microsoft-Exchange-Diagnostics-untrusted: 1;BN3PR03MB1510;5:YYfV7x0saE46+nOvOB611ERVj4xUTimMbDmEcgrsuMkiO2sVMApkNrYvFoGGMzAFD8xN21NMjyFqbwIV1NwUSAiqmUJ70OHGto7N24XGs6BcDG+NvzAEVKEYS91H6HQ4npQcrIKDZGzFqGNlrWhTTA==;24:z9MY8KVfI+K6QXR1Fyn/2uzhaIePUAeCtlUFt6PyT43olIw/3qrctP8BoXCLBHtwtCaGlgo1A675MMRU/A5gyMk79VgPNKb48FDnl1DNXRE=;20:azEj4XYV7clL83saL+3Ey8cEac3Ohg8ABuU92UnsIZW8tgtuQbPvUmFF6cCWarzcFBhXCBgl2ZuY76WMOif/AWnQ+fgouzOcNf0VNoe4E8MGOp9G43LDdu8R2CM1wdLBsLDsLQQYGEFjlYiY9uwyw1p4Ux8j9p5q2CHWqUe6y1U= SpamDiagnosticOutput: 1:23 SpamDiagnosticMetadata: NSPM SpamDiagnosticOutput: 1:23 SpamDiagnosticMetadata: NSPM X-MS-Exchange-Transport-CrossTenantHeadersStamped: BN3PR03MB1510 X-EOPAttributedMessage: 0 X-MS-Exchange-Transport-CrossTenantHeadersStripped: BN1AFFO11FD011.protection.gbl X-Microsoft-Exchange-Diagnostics: 1;BN1AFFO11FD011;1:2KpBtr7NoGbR482zs46T5Q1UhN2jJYARamHFFOrjv4MLcYzQDG6oCKRyiMZnLUqmdA6XtiXFDCJD0Q5nWRI02M8m6iNeWmsk8LhOfb0kpbkHBuluA0kN2/zShw+KpcJDvYmu5tDZ8CpiOxReTJSBQHS5YossbBBkZDkqA+m8GeZ8qiekR9IPc8W0FSMBGD2sdw83w8l73k7AggcDp84JKY5FF9iC8xJqvbPG8sGE/8hl6C/RTOoZw2svN29ScrWV1nvmtbm22IHl7tssIMSbrDRXPCdtbR8j0kyHmOpYgC4irD2UhUHrxLjM+Ph5c2eCYPzTPq+QElwIcLakoqc61O/ClUX2HyAaD70BKOeq0QNzDHNJg+zcio8W1GJRxq3j6XYXnz61qayuEt7gZULXuQ== X-Forefront-Antispam-Report: CIP:66.35.236.227;CTRY:US;IPV:NLI;EFV:NLI;SFV:NSPM;SFS:(10009020)(6009001)(2980300002)(339900001)(3050300001)(189002)(199003)(19580395003)(66066001)(6806004)(46102003)(19580405001)(47776003)(97736004)(64706001)(107886002)(81156007)(6070500001)(5001860100001)(5001960100002)(4001540100001)(5001830100001)(48376002)(86152002)(2201001)(50466002)(5001770100001)(85426001)(76176999)(50986999)(16796002)(86362001)(87936001)(50226001)(189998001)(21840400001)(77156002)(2950100001)(62966003)(68736005)(77096005)(229853001)(53416004)(92566002)(122386002)(40100003)(5003940100001)(33646002)(106466001)(7099028)(7059030)(2101003)(4001430100001);DIR:OUT;SFP:1101;SCL:1;SRVR:BLUPR03MB035;H:sj-itexedge03.altera.priv.altera.com;FPR:;SPF:Fail;PTR:InfoDomainNonexistent;MX:1;A:0;LANG:en; X-Microsoft-Exchange-Diagnostics: 1;BLUPR03MB035;2:paJPKnyhD4qhXZhVbEADX7EwqBOwkvrMuNcWlTrZwNfSjkEIcOOXFFw3GBvdehk0ynIn7EvSSE/ttg47EHN2A/PrEk88j9BBqGvabiqEPZmbU2FDW+lyLypi+MB5Ql4OJS98DHOu/MlIs4GEx9clGdCmSeVeDsg5E0wqLyJGIWs=;3:e5wK2tnhVvmjRU8vRL+OjWcdwRCW16lo6DegPt6qo6UxMRXfjXI25NeAiwsCO7Rx1bIaY/ZjRk8uK1YhsG84EKDoa4NgsVHePoGaTLs7t+C5cHiqqL6tFYk4MYT47hM2Q5c9xJU54gcCQw4zKd7sUV3WxTeILXwzgViPqcvffoBTnUUs907OAxKizDFXwx8ihea8tex9EGKx0WYtkRktcPYVlQFkQt2KSJC7Np9ZK7k=;25:xzeP0j+j/1HkFkfHguA2wvLN6rPEwxXpAo7NHgxcOc2xJvAXsyeprF+oV2LM3mo6wKixMx9jS1cVKoMkm2aXsNOh73lpNAIhjH4We26pOcfeu4tOhDDTec20tRBW3CD9a4iCn828ZaAulOaqh3p9GHAJJyeHZ294yx5VWehfIaqDQ+ASFxHGj/4LfQkN5naJkGDWrNW1gyWChv/Kt+G03OzPOkMI633S9zOg+TSBStBs5poUfRs/4+E2rkWaZUh7heJ9ZVpHfWP6ijky/NqQ/A==;20:IIufnG6/PSfsrsgqpjsioYVuCnIG6Qa3yu473X+LWfe6K/2D4kByBpkEj3m1RvK8zCMPNX4gxbaDsS7NQKNaUbfTTwfAeYRSotlCBQLP+zYhWr8R1udN7T/L2hZy35yG4gNFUoyWidzINXPSRKr4BAFp/MP+UG8v2zhRqsf8ozU= X-Microsoft-Exchange-Diagnostics: 1;BLUPR03MB035;4:RWO01KcuBjsfK7bzYD1woSz1I1kfqBFJS1ywjC0CFGusv+uteHN42MlcLPtC/3i/nyfBS75atDy+LGotgoKyhfclyiaRWT+AdjND5RH1GGDSYydpIgRzeheL9lkMM27+AmVtzH1rdAMYRMcvJrJRO4Xcg2yH/crmEtWs/3d/waCaMSyoTIUKPL7Eg878ErkfgNsCfnEDAAG0tiSmJOenuGW1DniJwMOSdUcoIq8KRF03e8S7wJhMKo2B0lcyOGtJ6cU3aUqq0qgF+GmNa1F1lNSAH959vF0b+zB7AtsS+lc= X-Forefront-PRVS: 0667289FF8 X-Microsoft-Exchange-Diagnostics: =?us-ascii?Q?1;BLUPR03MB035;23:1a/5EoPsuVgdsfqE20UFnjR01/AVBop8ihunQZmBf5?= =?us-ascii?Q?KiiwQw1MD5t069JnWvoO0GakoKnDiFQWYFM9AFKZ+IkzHxG+9Xh2p13oOKS8?= =?us-ascii?Q?Xok2Mc0SPLC8r/Wjj/uvbQE3D54jTn1fn5KS/RqKticHNa5a4H5wVUROb+8j?= =?us-ascii?Q?0NQKlCcDG67M/lgr4l5CwPBkfq5tPaR3qUU1opKwBIJigQ7tcFwh3+9TFfEK?= =?us-ascii?Q?Z44r4BgA7kGbd8AGBnXbY14BnL437PpODi3VyeCZiieVf2R81xmHo6NtHodj?= =?us-ascii?Q?xVaCI1ohc2M7fnJRTLSQ+515meGcT0gpY+pxmoZ0RwEDVe1u89XE+NN/ObGs?= =?us-ascii?Q?9Uy4XWS9XfNU9pyoH5FaqO6V+JbI+PfoT2GcnFx9iSFMSLSW2RLRTuOYNuwg?= =?us-ascii?Q?4XmUMzRmWF5J2rmw2OyukdpudgGXwdpRQlA+++JqOLEabKEpXhcTDdjIn4SD?= =?us-ascii?Q?CENnp6tIuhK10cnqea4BNImrb4BEkdE/ZTq2mIHh30dBvfHOEQdJOHCN20MI?= =?us-ascii?Q?AmDiLb5NRt0tfrce77HFZ7NQwHl1KyXbt2EaMgB6L0BNGw0Fe6kEP3BxkWp3?= =?us-ascii?Q?MXidkgqHpzJ4YGzib06yh0Vwisl3vH4ghFglEs4TsXBIHnhQv8AO/kFVUoH6?= =?us-ascii?Q?UBUnB0Jkay6qlR+m7+7UWbgxyM7kLhk6/02eOi3ltwcVKJv6dBEYN8PZODbL?= =?us-ascii?Q?v0+WCoBBOMd1yINUJeqJl7l4UNZkogN4wrD+iYmw4gK4vZutK9RMovpDHkmH?= =?us-ascii?Q?8BSxFIFp/tU/WLntK8OuZA5KNQeknSmwHYE1WW+j6VxPyinN4Qm38BPVHVMV?= =?us-ascii?Q?otaE1G2MDyKlJC3OOTWGJZmSP3mjjnkNAdzC09IlwMaDD69hwvM950JtFsC6?= =?us-ascii?Q?Ol3aOEF5lcwUF9TGi7n7uBqrdtx6nrYqd+EUR7K+/6kYcSB24zlEApDvZ3+X?= =?us-ascii?Q?Jraa2+ovnpA5wC7/INYsyZ+vAfoRrHxM6A6T/t0Mg9ixNi/JNg+V+4Kd4C+p?= =?us-ascii?Q?Ep9NSSLaTqjQ1Df1780CRbk0lI6PoHvA3HwSF8NmBAXw9OvR7yfNxy9XFeA9?= =?us-ascii?Q?nNxq3KdCW6zJg3VBVS8V7F8yuJSPQMp3Fp1NSHRSM4B42UPuydSmPa4ors2/?= =?us-ascii?Q?eJMopWHt51c26+5h3hrLYkWoETj4kJM+6oN6S+PXYxiHzilbplcBTckpqIGY?= =?us-ascii?Q?8K2BtP6n8JObeQT+vvyP57uipHDgzOnVoamd14+1QhDfVYUm35VGB5H7lzN9?= =?us-ascii?Q?KQAkgnwtsDNxGaDji6oFfLhCcmyEAefQ9v8uzcbiIC3i3I6A0ObSkUMSSDX2?= =?us-ascii?Q?DU/xaZekV2/kD8G2PoDrHjqa/Pjr1jLIcpmPIjfqRFSVW3H25vGMUO/yCrD9?= =?us-ascii?Q?z1UFCkOfAHQJI6WcHkmfQrfRI=3D?= X-Microsoft-Exchange-Diagnostics: 1;BLUPR03MB035;5:d41E3wdBKlZwylo0yXeiOASjV52xXLxVP+BHTz8FGCwPF0BfxszZq5Bvnz6xvISvkTXAkzcDMWdiNBRIBm4nqeGIPbaVcc4y09UYLVJgCqwIQyX4R6QpUXGaEV6a9LDCc54i6xAxAYCRGlr0rhogXQ==;24:4b7piTk96QcHQ+zfa9BtXuSIarwqiYUFURGNfIJB+UMqg5v0Xg+8RnHQ2IMwW7KyDCsz0OiC29xm4qNkewpYdb0k6TaKGCUQuwtTEZwLZWE=;20:n3V2/lWxX63CrEFxNSs5v6JtfGOBv9WLMTjbFlqPMOuGpsbxqFjbGTzQtYnFOC8rvuJbErvP4U8pNxcjCF3FlJ0IIWwc4yMBXtYMApIBTFt+GRWUTQAbIL8UDMhxOpsAAxSg0iTXCv6FEQuY/S5sh79NdekUZ1BJ2NUUjD7tP5s= X-OriginatorOrg: opensource.altera.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 13 Aug 2015 17:43:01.5606 (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: BLUPR03MB035 Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org From: Alan Tull Add a document on the new FPGA manager core. Signed-off-by: Alan Tull --- v9: initial version where this patch was added v10: requested cleanups to formatting and otherwise s/fpga/FPGA/g rewrite implementation section to not reference socfpga.c by name other rewrites Moved to Documentation/fpga/ --- Documentation/fpga/fpga-mgr.txt | 171 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 171 insertions(+) create mode 100644 Documentation/fpga/fpga-mgr.txt diff --git a/Documentation/fpga/fpga-mgr.txt b/Documentation/fpga/fpga-mgr.txt new file mode 100644 index 0000000..c5259e4 --- /dev/null +++ b/Documentation/fpga/fpga-mgr.txt @@ -0,0 +1,171 @@ +FPGA Manager Core + +Alan Tull 2015 + +Overview +======== + +The FPGA manager core exports a set of functions for programming an FPGA with +image. The API is manufacturer agnostic. All manufacturer specifics are +hidden away in a low level driver which registers a set of ops with the core. +The FPGA image data itself is very manufacturer specific, but for our purposes +it's just binary data. The FPGA manager core won't parse it. + + +API Functions: +============== + +To program the FPGA from a file or from a buffer: +------------------------------------------------- + + int fpga_mgr_buf_load(struct fpga_manager *mgr, u32 flags, + const char *buf, size_t count); + +Load the FPGA from an image which exists as a buffer in memory. + + int fpga_mgr_firmware_load(struct fpga_manager *mgr, u32 flags, + const char *image_name); + +Load the FPGA from an image which exists as a file. The image file must be on +the firmware search path (see the firmware class documentation). + +For both these functions, flags == 0 for normal full reconfiguration or +FPGA_MGR_PARTIAL_RECONFIG for partial reconfiguration. If successful, the FPGA +ends up in operating mode. Return 0 on success or a negative error code. + + +To get/put a reference to a FPGA manager: +----------------------------------------- + + struct fpga_manager *of_fpga_mgr_get(struct device_node *node); + + void fpga_mgr_put(struct fpga_manager *mgr); + +Given a DT node, get an exclusive reference to a FPGA manager or release +the reference. + + +To register or unregister the low level FPGA-specific driver: +------------------------------------------------------------- + + 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); + +Use of these two functions is described below in "How To Support a new FPGA +device." + + +How to write an image buffer to a supported FPGA +================================================ +/* Include to get the API */ +#include + +/* device node that specifies the FPGA manager to use */ +struct device_node *mgr_node = ... + +/* FPGA image is in this buffer. count is size of the buffer. */ +char *buf = ... +int count = ... + +/* flags indicates whether to do full or partial reconfiguration */ +int flags = 0; + +int ret; + +/* Get exclusive control of FPGA manager */ +struct fpga_manager *mgr = of_fpga_mgr_get(mgr_node); + +/* Load the buffer to the FPGA */ +ret = fpga_mgr_buf_load(mgr, flags, buf, count); + +/* Release the FPGA manager */ +fpga_mgr_put(mgr); + + +How to write an image file to a supported FPGA +============================================== +/* Include to get the API */ +#include + +/* device node that specifies the FPGA manager to use */ +struct device_node *mgr_node = ... + +/* FPGA image is in this file which is on the firmware search path */ +const char *path = "fpga-image-9.rbf" + +/* flags indicates whether to do full or partial reconfiguration */ +int flags = 0; + +int ret; + +/* Get exclusive control of FPGA manager */ +struct fpga_manager *mgr = of_fpga_mgr_get(mgr_node); + +/* Get the firmware image (path) and load it to the FPGA */ +ret = fpga_mgr_firmware_load(mgr, flags, path); + +/* Release the FPGA manager */ +fpga_mgr_put(mgr); + + +How to support a new FPGA device +================================ +To add another FPGA manager, write a driver that implements a set of ops. The +probe function calls fpga_mgr_register(), such as: + +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, +}; + +static int socfpga_fpga_probe(struct platform_device *pdev) +{ + struct device *dev = &pdev->dev; + struct socfpga_fpga_priv *priv; + int ret; + + priv = devm_kzalloc(dev, sizeof(*priv), GFP_KERNEL); + if (!priv) + return -ENOMEM; + + /* ... do ioremaps, get interrupts, etc. and save + them in priv... */ + + return fpga_mgr_register(dev, "Altera SOCFPGA FPGA Manager", + &socfpga_fpga_ops, priv); +} + +static int socfpga_fpga_remove(struct platform_device *pdev) +{ + fpga_mgr_unregister(&pdev->dev); + + return 0; +} + + +The ops will implement whatever device specific register writes are needed to +do the programming sequence for this particular FPGA. These ops return 0 for +success or negative error codes otherwise. + +The programming sequence 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 writes a buffer to the FPGA. The buffer may be contain the +whole FPGA image or may be a smaller chunk of an FPGA image. In the latter +case, this function is called multiple times for successive chunks. + +The .write_complete function is called after all the image has been written +to put the FPGA into operating mode. + +The ops include a .state function which will read the hardware FPGA manager and +return a code of type enum fpga_mgr_states. It doesn't result in a change in +hardware state. -- 1.7.9.5