FPGA Manager Framework
Subsystems (2)
v11 cover FPGA Manager Framework
From: Alan Tull <[email protected]>
Hi Greg,
I'm resending v11
The changes requested for v12 are minor. We can fix them upstream in some small patches. Thanks for everybody's support and help in reviewing these.
Alan
This patch set adds the FPGA manager core which exports API functions that write an image to a FPGA
I'm holding off on the DT overlay support a little for now.
The core's API is minimal to start with: only 6 functions. This gives a manufacturer-agnostic interface for programming FPGA's such that higher level interfaces (such as DT Overlays) can be shared.
Alan Tull (4):
usage documentation for FPGA manager core fpga manager: add sysfs interface document add FPGA manager core
fpga manager: add driver for socfpga fpga manager
Documentation/ABI/testing/sysfs-class-fpga-manager | 37 ++ Documentation/fpga/fpga-mgr.txt | 171 ++++++ drivers/Kconfig | 2 + drivers/Makefile | 1 + drivers/fpga/Kconfig | 24 + drivers/fpga/Makefile | 9 + drivers/fpga/fpga-mgr.c | 382 ++++++++++++ drivers/fpga/socfpga.c | 616 ++++++++++++++++++++ include/linux/fpga/fpga-mgr.h | 127 ++++ 9 files changed, 1369 insertions(+) create mode 100644 Documentation/ABI/testing/sysfs-class-fpga-manager create mode 100644 Documentation/fpga/fpga-mgr.txt create mode 100644 drivers/fpga/Kconfig create mode 100644 drivers/fpga/Makefile create mode 100644 drivers/fpga/fpga-mgr.c create mode 100644 drivers/fpga/socfpga.c create mode 100644 include/linux/fpga/fpga-mgr.h
Signature · 1 line
1.7.9.5
PATCH v11 1/4 usage documentation for FPGA manager core
From: Alan Tull <[email protected]>
Add a document on the new FPGA manager core.
---
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/
v11: s/with image/with an image/
s/on the path/in the path/
--- Documentation/fpga/fpga-mgr.txt | 171 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 171 insertions(+) create mode 100644 Documentation/fpga/fpga-mgr.txt
Documentation/fpga/fpga-mgr.txt new file +171 -0
@@ -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 +an 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 <linux/fpga/fpga-mgr.h> + +/* 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 <linux/fpga/fpga-mgr.h> + +/* device node that specifies the FPGA manager to use */ +struct device_node *mgr_node = ... + +/* FPGA image is in this file which is in 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.
Signature · 1 line
1.7.9.5
PATCH v11 2/4 fpga manager: add sysfs interface document
In reply to [email protected]From: Alan Tull <[email protected]>
Add documentation under drivers/staging for new fpga manager's sysfs interface.
---
v5 : (actually second version, but keeping version numbers
aligned with rest of patch series)
Move document to drivers/staging/fpga/Documentation/ABI
v6 : No change in this patch for v6 of the patch set v7 : No change in this patch for v7 of the patch set v8 : No change in this patch for v8 of the patch set
v9 : Remove 'firmware' and 'reset' files
Update state strings
v10 : Clarifications about state attribute
Move to Documentation/ABI/testing/
v11 : No change in this patch for v11 of the patch set
--- Documentation/ABI/testing/sysfs-class-fpga-manager | 37 ++++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 Documentation/ABI/testing/sysfs-class-fpga-manager
Documentation/ABI/testing/sysfs-class-fpga-manager new file +37 -0
@@ -0,0 +1,37 @@ +What: /sys/class/fpga_manager/<fpga>/name +Date: August 2015 +KernelVersion: 4.3 +Contact: Alan Tull <[email protected]> +Description: Name of low level fpga manager driver. + +What: /sys/class/fpga_manager/<fpga>/state +Date: August 2015 +KernelVersion: 4.3 +Contact: Alan Tull <[email protected]> +Description: Read fpga manager state as a string. + The intent is to provide enough detail that if something goes + wrong during FPGA programming (something that the driver can't + fix) then userspace can know, i.e. if the firmware request + fails, that could be due to not being able to find the firmware + file. + + This is a superset of FPGA states and fpga manager driver + states. The fpga manager driver is walking through these steps + to get the FPGA into a known operating state. It's a sequence, + though some steps may get skipped. Valid FPGA states will vary + by manufacturer; this is a superset. + + * unknown = can't determine state + * power off = FPGA power is off + * power up = FPGA reports power is up + * reset = FPGA held in reset state + * firmware request = firmware class request in progress + * firmware request error = firmware request failed + * write init = preparing FPGA for programming + * write init error = Error while preparing FPGA for + programming + * write = FPGA ready to receive image data + * write error = Error while programming + * write complete = Doing post programming steps + * write complete error = Error while doing post programming + * operating = FPGA is programmed and operating
Signature · 1 line
1.7.9.5
PATCH v11 3/4 add FPGA manager core
In reply to [email protected]From: Alan Tull <[email protected]>
API to support programming FPGA's.
The following functions are exported as GPL:
* fpga_mgr_buf_load
Load fpga from image in buffer
* fpga_mgr_firmware_load
Request firmware and load it to the FPGA.
* fpga_mgr_register
* fpga_mgr_unregister
FPGA device drivers can be added by calling
fpga_mgr_register() to register a set of
fpga_manager_ops to do device specific stuff.
* of_fpga_mgr_get
* fpga_mgr_put
Get/put a reference to a fpga manager.
The following sysfs files are created:
* /sys/class/fpga_manager/<fpga>/name
Name of low level driver.
* /sys/class/fpga_manager/<fpga>/state
State of fpga manager
---
v2: s/mangager/manager/
check for invalid request_nr
add fpga reset interface
rework the state code
remove FPGA_MGR_FAIL flag
add _ERR states to fpga manager states enum low level state op now returns a state enum value initialize framework state from driver state op remove unused fpga read stuff
merge sysfs.c into fpga-mgr.c
move suspend/resume from bus.c to fpga-mgr.c
v3: Add struct device to fpga_manager (not as a pointer)
Add to_fpga_manager
Don't get irq in fpga-mgr.c (let low level driver do it) remove from struct fpga_manager: nr, np, parent get rid of fpga_mgr_get_new_minor()
simplify fpga_manager_register:
reorder parameters
use dev instead of pdev
get rid of code that used to make more sense when this
was a char driver, don't alloc_chrdev_region
use a mutex instead of flags
v4: Move to drivers/staging
v5: Make some things be static
Kconfig: add 'if FPGA'
Makefile: s/fpga-mgr-core.o/fpga-mgr.o/ clean up includes
use enum fpga_mgr_states instead of int static const char *state_str
use DEVICE_ATTR_RO/RW/WO and ATTRIBUTE_GROUPS return -EINVAL instead of BUG_ON
move ida_simple_get after kzalloc
clean up fpga_mgr_remove
fpga-mgr.h: remove '#if IS_ENABLED(CONFIG_FPGA)' add kernel-doc documentation
Move header to new include/linux/fpga folder static const struct fpga_mgr_ops dev_info msg simplified
v6: no statically allocated string for image_name
kernel doc fixes
changes regarding enabling SYSFS for fpga mgr
Makefile cleanup
v7: no change in this patch for v7 of the patchset
v8: no change in this patch for v8 of the patchset
v9: remove writable attributes 'firmware' and 'reset'
remove suspend/resume support for now
remove list of fpga managers; use class device iterators instead simplify locking by giving out only one ref exclusively add device tree support
add flags
par down API into fewer functions
update copyright year
rename some functions for clarity
clean up unnecessary #includes
add some error messages
write_init may need to look at buffer header, so add to params
v10: Make this a tristate in Kconfig
pass flags parameter to write_complete
use BIT(0) in macro
move to drivers/fpga
fpga_manager_get/put call module_try_get/module_put
v11: Set state to 'operating' after successfully programming the FPGA
--- drivers/Kconfig | 2 + drivers/Makefile | 1 + drivers/fpga/Kconfig | 14 ++ drivers/fpga/Makefile | 8 + drivers/fpga/fpga-mgr.c | 382 +++++++++++++++++++++++++++++++++++++++++ include/linux/fpga/fpga-mgr.h | 127 ++++++++++++++ 6 files changed, 534 insertions(+) create mode 100644 drivers/fpga/Kconfig create mode 100644 drivers/fpga/Makefile create mode 100644 drivers/fpga/fpga-mgr.c create mode 100644 include/linux/fpga/fpga-mgr.h
drivers/Kconfig +2 -0
@@ -184,4 +184,6 @@ source "drivers/android/Kconfig" source "drivers/nvdimm/Kconfig" +source "drivers/fpga/Kconfig" + endmenu
drivers/Makefile +1 -0
@@ -165,3 +165,4 @@ obj-$(CONFIG_RAS) += ras/ obj-$(CONFIG_THUNDERBOLT) += thunderbolt/ obj-$(CONFIG_CORESIGHT) += hwtracing/coresight/ obj-$(CONFIG_ANDROID) += android/ +obj-$(CONFIG_FPGA) += fpga/
drivers/fpga/Kconfig new file +14 -0
@@ -0,0 +1,14 @@ +# +# FPGA framework configuration +# + +menu "FPGA Configuration Support" + +config FPGA + tristate "FPGA Configuration Framework" + help + Say Y here if you want support for configuring FPGAs from the + kernel. The FPGA framework adds a FPGA manager class and FPGA + manager drivers. + +endmenu
drivers/fpga/Makefile new file +8 -0
@@ -0,0 +1,8 @@ +# +# Makefile for the fpga framework and fpga manager drivers. +# + +# Core FPGA Manager Framework +obj-$(CONFIG_FPGA) += fpga-mgr.o + +# FPGA Manager Drivers
drivers/fpga/fpga-mgr.c new file +382 -0
382 lines not on this page · raw message
include/linux/fpga/fpga-mgr.h new file +127 -0
127 lines not on this page · raw message
Signature · 1 line
1.7.9.5
PATCH v11 4/4 fpga manager: add driver for socfpga fpga manager
In reply to [email protected]From: Alan Tull <[email protected]>
Add driver to fpga manager framework to allow configuration of FPGA in Altera SoCFPGA parts.
---
v2: fpga_manager struct now contains struct device
fpga_manager_register parameters now take device
v3: skip a version to align versions
v4: move to drivers/staging
v5: fix array_size.cocci warnings
fix platform_no_drv_owner.cocci warnings
Remove .owner = THIS_MODULE
include asm/irq.h
clean up list of includes
use altera_fpga_reset for ops
use enum fpga_mgr_states or u32 as needed
use devm_request_irq
check irq <= 0 instead of == NO_IRQ
Use ARRAY_SIZE
rename altera -> socfpga
static const socfpga_fpga_ops
header moved to linux/fpga/ folder
remove ifdef'ed code
use platform_get_resource and platform_get_irq move .probe and .remove lines adjacent
use module_platform_driver
use __maybe_unused
only need to 'if (IS_ENABLED(CONFIG_REGULATOR))' in one fn fix "unsigned 'mode' is never < 0"
v6: return error for (unused) default of case statement
v7: PTR_ERR should access the value just tested by IS_ERR
v8: change compatible string to be more chip specific
v9: update copyright year
remove suspend/resume support and regulators use updated fn names for register/unregister use updated params for write_init
check for partial reconfiguration request
v10: make tristate in Kconfig
clean up include
add flags param to write_complete()
move do drivers/fpga
v11: No code change in this patch for v11 of the patch set
Adding Moritz' ACK
--- drivers/fpga/Kconfig | 10 + drivers/fpga/Makefile | 1 + drivers/fpga/socfpga.c | 616 ++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 627 insertions(+) create mode 100644 drivers/fpga/socfpga.c
drivers/fpga/Kconfig +10 -0
@@ -11,4 +11,14 @@ config FPGA kernel. The FPGA framework adds a FPGA manager class and FPGA manager drivers. +if FPGA + +config FPGA_MGR_SOCFPGA + tristate "Altera SOCFPGA FPGA Manager" + depends on ARCH_SOCFPGA + help + FPGA manager driver support for Altera SOCFPGA. + +endif # FPGA + endmenu
drivers/fpga/Makefile +1 -0
@@ -6,3 +6,4 @@ obj-$(CONFIG_FPGA) += fpga-mgr.o # FPGA Manager Drivers +obj-$(CONFIG_FPGA_MGR_SOCFPGA) += socfpga.o
drivers/fpga/socfpga.c new file +616 -0
616 lines not on this page · raw message
Signature · 1 line
1.7.9.5
Quoted 9 lines · On Wed, Oct 07, 2015 at 04:36:25PM +0100, [email protected] wrote:
From: Alan Tull <[email protected]>
Hi Greg,
I'm resending v11
The changes requested for v12 are minor. We can fix them upstream in some small patches. Thanks for everybody's support and help in reviewing these.
Looks great, thanks for working so hard on this over the past year(s), nice job everyone. I've queued this up in my tree now.
thanks,
greg k-h
Hi Greg, Alan
Quoted 10 lines · Greg KH
Quoted 9 lines · On Wed, Oct 07, 2015 at 04:36:25PM +0100, [email protected] wrote:
From: Alan Tull <[email protected]>
Hi Greg,
I'm resending v11
The changes requested for v12 are minor. We can fix them upstream in some small patches. Thanks for everybody's support and help in reviewing these.
Agreed, It's been a recurring theme the last few days that people should step up and volunteer to co-maintain code.
I have a vested interest in a working upstream solution for FPGA manager for my devices, so if you need help, I'll be around.
Quoted 3 lines
Looks great, thanks for working so hard on this over the past year(s), nice job everyone. I've queued this up in my tree now.
Awesome! I'll submit my series for the Xilinx equivalent low level driver within the next few days, great to finally see things moving.
Quoted 3 lines
thanks,
greg k-h
Cheers,
Moritz
Quoted 10 lines · Moritz Fischer
Hi Greg, Alan
Quoted 7 lines · Greg KH
Quoted 6 lines · On Wed, Oct 07, 2015 at 04:36:25PM +0100, [email protected] wrote:
From: Alan Tull <[email protected]>
Hi Greg,
I'm resending v11
Quoted 8 lines
Quoted 3 lines
Quoted 3 lines
The changes requested for v12 are minor. We can fix them upstream in some small patches. Thanks for everybody's support and help in reviewing these.
Agreed, It's been a recurring theme the last few days that people should step up and volunteer to co-maintain code.
I have a vested interest in a working upstream solution for FPGA manager for my devices, so if you need help, I'll be around.
Thank you Moritz.
Quoted 4 lines
Quoted 3 lines
Looks great, thanks for working so hard on this over the past year(s), nice job everyone. I've queued this up in my tree now.
Hi Greg,
Thanks!
Alan