All of lore.kernel.org
 help / color / mirror / Atom feed
* [PATCH 00/14] fpga api changes and kernel-doc fixup
@ 2018-05-16 23:49 Alan Tull
  2018-05-16 23:49 ` [PATCH 01/14] fpga: region: don't use drvdata in common fpga code Alan Tull
                   ` (14 more replies)
  0 siblings, 15 replies; 26+ messages in thread
From: Alan Tull @ 2018-05-16 23:49 UTC (permalink / raw)
  To: Greg Kroah-Hartman, Jonathan Corbet, Moritz Fischer
  Cc: linux-kernel, linux-fpga, Alan Tull

I'm posting these all together because they are interdependent.

Patches 1-4 are a repost of v4 of the FPGA api change.

Patch 5 is a repost of adding SPDX to my fpga code

Patch 6-12 update the fpga kernel-doc documentation and move
existing .txt fpga documentation to driver-api ReST documents.

Patch 13 is a minor documentation fix

Patch 14 updates MAINTAINERS for the new driver-api/fpga directory

Alan Tull (14):
  fpga: region: don't use drvdata in common fpga code
  fpga: manager: change api, don't use drvdata
  fpga: bridge: change api, don't use drvdata
  fpga: region: change api, add fpga_region_create/free
  fpga: use SPDX
  fpga: mgr: kernel-doc fixes
  fpga: bridge: kernel-doc fixes
  fpga: region: kernel-doc fixes
  Documentation: fpga: move fpga overview to driver-api
  documentation: fpga: move fpga-mgr.txt to driver-api
  documentation: fpga: add bridge document to driver-api
  documentation: fpga: move fpga-region.txt to driver-api
  fpga: clarify that unregister functions also free
  MAINTAINERS: Add driver-api/fpga path

 Documentation/driver-api/fpga/fpga-bridge.rst |  49 ++++++
 Documentation/driver-api/fpga/fpga-mgr.rst    | 220 ++++++++++++++++++++++++++
 Documentation/driver-api/fpga/fpga-region.rst | 102 ++++++++++++
 Documentation/driver-api/fpga/index.rst       |  13 ++
 Documentation/driver-api/fpga/intro.rst       |  54 +++++++
 Documentation/driver-api/index.rst            |   1 +
 Documentation/fpga/fpga-mgr.txt               | 199 -----------------------
 Documentation/fpga/fpga-region.txt            |  95 -----------
 Documentation/fpga/overview.txt               |  23 ---
 MAINTAINERS                                   |   1 +
 drivers/fpga/altera-cvp.c                     |  19 ++-
 drivers/fpga/altera-fpga2sdram.c              |  34 ++--
 drivers/fpga/altera-freeze-bridge.c           |  35 ++--
 drivers/fpga/altera-hps2fpga.c                |  37 +++--
 drivers/fpga/altera-pr-ip-core-plat.c         |  13 +-
 drivers/fpga/altera-pr-ip-core.c              |  31 ++--
 drivers/fpga/altera-ps-spi.c                  |  20 ++-
 drivers/fpga/fpga-bridge.c                    |  86 +++++-----
 drivers/fpga/fpga-mgr.c                       | 129 +++++++++------
 drivers/fpga/fpga-region.c                    |  86 ++++++----
 drivers/fpga/ice40-spi.c                      |  21 ++-
 drivers/fpga/machxo2-spi.c                    |  20 ++-
 drivers/fpga/of-fpga-region.c                 |  28 +---
 drivers/fpga/socfpga-a10.c                    |  28 ++--
 drivers/fpga/socfpga.c                        |  32 ++--
 drivers/fpga/ts73xx-fpga.c                    |  20 ++-
 drivers/fpga/xilinx-pr-decoupler.c            |  22 ++-
 drivers/fpga/xilinx-spi.c                     |  20 ++-
 drivers/fpga/zynq-fpga.c                      |  14 +-
 include/linux/fpga/altera-pr-ip-core.h        |  13 +-
 include/linux/fpga/fpga-bridge.h              |   9 +-
 include/linux/fpga/fpga-mgr.h                 |  23 +--
 include/linux/fpga/fpga-region.h              |  13 +-
 33 files changed, 890 insertions(+), 620 deletions(-)
 create mode 100644 Documentation/driver-api/fpga/fpga-bridge.rst
 create mode 100644 Documentation/driver-api/fpga/fpga-mgr.rst
 create mode 100644 Documentation/driver-api/fpga/fpga-region.rst
 create mode 100644 Documentation/driver-api/fpga/index.rst
 create mode 100644 Documentation/driver-api/fpga/intro.rst
 delete mode 100644 Documentation/fpga/fpga-mgr.txt
 delete mode 100644 Documentation/fpga/fpga-region.txt
 delete mode 100644 Documentation/fpga/overview.txt

-- 
2.7.4

^ permalink raw reply	[flat|nested] 26+ messages in thread
* [PATCH 01/14] fpga: region: don't use drvdata in common fpga code
  2018-05-16 23:49 [PATCH 00/14] fpga api changes and kernel-doc fixup Alan Tull
@ 2018-05-16 23:49 ` Alan Tull
  2018-05-16 23:49 ` [PATCH 02/14] fpga: manager: change api, don't use drvdata Alan Tull
                   ` (13 subsequent siblings)
  14 siblings, 0 replies; 26+ messages in thread
From: Alan Tull @ 2018-05-16 23:49 UTC (permalink / raw)
  To: Greg Kroah-Hartman, Jonathan Corbet, Moritz Fischer
  Cc: linux-kernel, linux-fpga, Alan Tull

Changes to fpga_region_register function to not set drvdata.

Setting drvdata is fine for DT based devices that will have one region
per platform device.  However PCIe based devices may have multiple
FPGA regions under one PCIe device.  Without these changes, the PCIe
solution has to create an extra device for each child region to hold
drvdata.

Signed-off-by: Alan Tull <atull@kernel.org>
Reported-by: Jiuyue Ma <majiuyue@huawei.com>
Signed-off-by: Moritz Fischer <mdf@kernel.org>
---
 drivers/fpga/fpga-region.c    | 1 -
 drivers/fpga/of-fpga-region.c | 1 +
 2 files changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/fpga/fpga-region.c b/drivers/fpga/fpga-region.c
index cb0603e..f634a8e 100644
--- a/drivers/fpga/fpga-region.c
+++ b/drivers/fpga/fpga-region.c
@@ -183,7 +183,6 @@ int fpga_region_register(struct device *dev, struct fpga_region *region)
 	region->dev.parent = dev;
 	region->dev.of_node = dev->of_node;
 	region->dev.id = id;
-	dev_set_drvdata(dev, region);
 
 	ret = dev_set_name(&region->dev, "region%d", id);
 	if (ret)
diff --git a/drivers/fpga/of-fpga-region.c b/drivers/fpga/of-fpga-region.c
index 119ff75..35e7e8c 100644
--- a/drivers/fpga/of-fpga-region.c
+++ b/drivers/fpga/of-fpga-region.c
@@ -438,6 +438,7 @@ static int of_fpga_region_probe(struct platform_device *pdev)
 		goto eprobe_mgr_put;
 
 	of_platform_populate(np, fpga_region_of_match, NULL, &region->dev);
+	dev_set_drvdata(dev, region);
 
 	dev_info(dev, "FPGA Region probed\n");
 
-- 
2.7.4

^ permalink raw reply related	[flat|nested] 26+ messages in thread
* [PATCH 02/14] fpga: manager: change api, don't use drvdata
  2018-05-16 23:49 [PATCH 00/14] fpga api changes and kernel-doc fixup Alan Tull
  2018-05-16 23:49 ` [PATCH 01/14] fpga: region: don't use drvdata in common fpga code Alan Tull
@ 2018-05-16 23:49 ` Alan Tull
  2018-05-16 23:49 ` [PATCH 03/14] fpga: bridge: " Alan Tull
                   ` (12 subsequent siblings)
  14 siblings, 0 replies; 26+ messages in thread
From: Alan Tull @ 2018-05-16 23:49 UTC (permalink / raw)
  To: Greg Kroah-Hartman, Jonathan Corbet, Moritz Fischer
  Cc: linux-kernel, linux-fpga, Alan Tull

Change fpga_mgr_register to not set or use drvdata.  This supports
the case where a PCIe device has more than one manager.

Add fpga_mgr_create/free functions.  Change fpga_mgr_register and
fpga_mgr_unregister functions to take the mgr struct as their only
parameter.

  struct fpga_manager *fpga_mgr_create(struct device *dev,
                const char *name,
                const struct fpga_manager_ops *mops,
                void *priv);
  void fpga_mgr_free(struct fpga_manager *mgr);
  int fpga_mgr_register(struct fpga_manager *mgr);
  void fpga_mgr_unregister(struct fpga_manager *mgr);

Update the drivers that call fpga_mgr_register with the new API.

Signed-off-by: Alan Tull <atull@kernel.org>
[Moritz: Fixup whitespace issue]
Reported-by: Jiuyue Ma <majiuyue@huawei.com>
Signed-off-by: Moritz Fischer <mdf@kernel.org>
---
 Documentation/fpga/fpga-mgr.txt  | 35 +++++++++++++-----
 drivers/fpga/altera-cvp.c        | 19 +++++++---
 drivers/fpga/altera-pr-ip-core.c | 18 ++++++++--
 drivers/fpga/altera-ps-spi.c     | 20 +++++++++--
 drivers/fpga/fpga-mgr.c          | 78 ++++++++++++++++++++++++++--------------
 drivers/fpga/ice40-spi.c         | 21 ++++++++---
 drivers/fpga/machxo2-spi.c       | 20 ++++++++---
 drivers/fpga/socfpga-a10.c       | 14 ++++++--
 drivers/fpga/socfpga.c           | 19 ++++++++--
 drivers/fpga/ts73xx-fpga.c       | 20 +++++++++--
 drivers/fpga/xilinx-spi.c        | 20 +++++++++--
 drivers/fpga/zynq-fpga.c         | 14 ++++++--
 include/linux/fpga/fpga-mgr.h    | 10 +++---
 13 files changed, 237 insertions(+), 71 deletions(-)

diff --git a/Documentation/fpga/fpga-mgr.txt b/Documentation/fpga/fpga-mgr.txt
index cc6413e..86b6df6 100644
--- a/Documentation/fpga/fpga-mgr.txt
+++ b/Documentation/fpga/fpga-mgr.txt
@@ -63,17 +63,23 @@ The user should call fpga_mgr_lock and verify that it returns 0 before
 attempting to program the FPGA.  Likewise, the user should call
 fpga_mgr_unlock when done programming the FPGA.
 
+To alloc/free a FPGA manager struct:
+------------------------------------
+
+	struct fpga_manager *fpga_mgr_create(struct device *dev,
+					     const char *name,
+					     const struct fpga_manager_ops *mops,
+					     void *priv);
+	void fpga_mgr_free(struct fpga_manager *mgr);
 
 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);
+	int fpga_mgr_register(struct fpga_manager *mgr);
 
-	void fpga_mgr_unregister(struct device *dev);
+	void fpga_mgr_unregister(struct fpga_manager *mgr);
 
-Use of these two functions is described below in "How To Support a new FPGA
+Use of these functions is described below in "How To Support a new FPGA
 device."
 
 
@@ -148,6 +154,7 @@ static int socfpga_fpga_probe(struct platform_device *pdev)
 {
 	struct device *dev = &pdev->dev;
 	struct socfpga_fpga_priv *priv;
+	struct fpga_manager *mgr;
 	int ret;
 
 	priv = devm_kzalloc(dev, sizeof(*priv), GFP_KERNEL);
@@ -157,13 +164,25 @@ static int socfpga_fpga_probe(struct platform_device *pdev)
 	/* ... do ioremaps, get interrupts, etc. and save
 	   them in priv... */
 
-	return fpga_mgr_register(dev, "Altera SOCFPGA FPGA Manager",
-				 &socfpga_fpga_ops, priv);
+	mgr = fpga_mgr_create(dev, "Altera SOCFPGA FPGA Manager",
+			      &socfpga_fpga_ops, priv);
+	if (!mgr)
+		return -ENOMEM;
+
+	platform_set_drvdata(pdev, mgr);
+
+	ret = fpga_mgr_register(mgr);
+	if (ret)
+		fpga_mgr_free(mgr);
+
+	return ret;
 }
 
 static int socfpga_fpga_remove(struct platform_device *pdev)
 {
-	fpga_mgr_unregister(&pdev->dev);
+	struct fpga_manager *mgr = platform_get_drvdata(pdev);
+
+	fpga_mgr_unregister(mgr);
 
 	return 0;
 }
diff --git a/drivers/fpga/altera-cvp.c b/drivers/fpga/altera-cvp.c
index 77b04e4..dd4edd8 100644
--- a/drivers/fpga/altera-cvp.c
+++ b/drivers/fpga/altera-cvp.c
@@ -401,6 +401,7 @@ static int altera_cvp_probe(struct pci_dev *pdev,
 			    const struct pci_device_id *dev_id)
 {
 	struct altera_cvp_conf *conf;
+	struct fpga_manager *mgr;
 	u16 cmd, val;
 	int ret;
 
@@ -452,16 +453,24 @@ static int altera_cvp_probe(struct pci_dev *pdev,
 	snprintf(conf->mgr_name, sizeof(conf->mgr_name), "%s @%s",
 		 ALTERA_CVP_MGR_NAME, pci_name(pdev));
 
-	ret = fpga_mgr_register(&pdev->dev, conf->mgr_name,
-				&altera_cvp_ops, conf);
-	if (ret)
+	mgr = fpga_mgr_create(&pdev->dev, conf->mgr_name,
+			      &altera_cvp_ops, conf);
+	if (!mgr)
+		return -ENOMEM;
+
+	pci_set_drvdata(pdev, mgr);
+
+	ret = fpga_mgr_register(mgr);
+	if (ret) {
+		fpga_mgr_free(mgr);
 		goto err_unmap;
+	}
 
 	ret = driver_create_file(&altera_cvp_driver.driver,
 				 &driver_attr_chkcfg);
 	if (ret) {
 		dev_err(&pdev->dev, "Can't create sysfs chkcfg file\n");
-		fpga_mgr_unregister(&pdev->dev);
+		fpga_mgr_unregister(mgr);
 		goto err_unmap;
 	}
 
@@ -483,7 +492,7 @@ static void altera_cvp_remove(struct pci_dev *pdev)
 	u16 cmd;
 
 	driver_remove_file(&altera_cvp_driver.driver, &driver_attr_chkcfg);
-	fpga_mgr_unregister(&pdev->dev);
+	fpga_mgr_unregister(mgr);
 	pci_iounmap(pdev, conf->map);
 	pci_release_region(pdev, CVP_BAR);
 	pci_read_config_word(pdev, PCI_COMMAND, &cmd);
diff --git a/drivers/fpga/altera-pr-ip-core.c b/drivers/fpga/altera-pr-ip-core.c
index a7b31f9..eea5217 100644
--- a/drivers/fpga/altera-pr-ip-core.c
+++ b/drivers/fpga/altera-pr-ip-core.c
@@ -187,6 +187,8 @@ static const struct fpga_manager_ops alt_pr_ops = {
 int alt_pr_register(struct device *dev, void __iomem *reg_base)
 {
 	struct alt_pr_priv *priv;
+	struct fpga_manager *mgr;
+	int ret;
 	u32 val;
 
 	priv = devm_kzalloc(dev, sizeof(*priv), GFP_KERNEL);
@@ -201,15 +203,27 @@ int alt_pr_register(struct device *dev, void __iomem *reg_base)
 		(val & ALT_PR_CSR_STATUS_MSK) >> ALT_PR_CSR_STATUS_SFT,
 		(int)(val & ALT_PR_CSR_PR_START));
 
-	return fpga_mgr_register(dev, dev_name(dev), &alt_pr_ops, priv);
+	mgr = fpga_mgr_create(dev, dev_name(dev), &alt_pr_ops, priv);
+	if (!mgr)
+		return -ENOMEM;
+
+	dev_set_drvdata(dev, mgr);
+
+	ret = fpga_mgr_register(mgr);
+	if (ret)
+		fpga_mgr_free(mgr);
+
+	return ret;
 }
 EXPORT_SYMBOL_GPL(alt_pr_register);
 
 int alt_pr_unregister(struct device *dev)
 {
+	struct fpga_manager *mgr = dev_get_drvdata(dev);
+
 	dev_dbg(dev, "%s\n", __func__);
 
-	fpga_mgr_unregister(dev);
+	fpga_mgr_unregister(mgr);
 
 	return 0;
 }
diff --git a/drivers/fpga/altera-ps-spi.c b/drivers/fpga/altera-ps-spi.c
index 06d212a..24b25c6 100644
--- a/drivers/fpga/altera-ps-spi.c
+++ b/drivers/fpga/altera-ps-spi.c
@@ -238,6 +238,8 @@ static int altera_ps_probe(struct spi_device *spi)
 {
 	struct altera_ps_conf *conf;
 	const struct of_device_id *of_id;
+	struct fpga_manager *mgr;
+	int ret;
 
 	conf = devm_kzalloc(&spi->dev, sizeof(*conf), GFP_KERNEL);
 	if (!conf)
@@ -273,13 +275,25 @@ static int altera_ps_probe(struct spi_device *spi)
 	snprintf(conf->mgr_name, sizeof(conf->mgr_name), "%s %s",
 		 dev_driver_string(&spi->dev), dev_name(&spi->dev));
 
-	return fpga_mgr_register(&spi->dev, conf->mgr_name,
-				 &altera_ps_ops, conf);
+	mgr = fpga_mgr_create(&spi->dev, conf->mgr_name,
+			      &altera_ps_ops, conf);
+	if (!mgr)
+		return -ENOMEM;
+
+	spi_set_drvdata(spi, mgr);
+
+	ret = fpga_mgr_register(mgr);
+	if (ret)
+		fpga_mgr_free(mgr);
+
+	return ret;
 }
 
 static int altera_ps_remove(struct spi_device *spi)
 {
-	fpga_mgr_unregister(&spi->dev);
+	struct fpga_manager *mgr = spi_get_drvdata(spi);
+
+	fpga_mgr_unregister(mgr);
 
 	return 0;
 }
diff --git a/drivers/fpga/fpga-mgr.c b/drivers/fpga/fpga-mgr.c
index 9939d2c..0a5181d 100644
--- a/drivers/fpga/fpga-mgr.c
+++ b/drivers/fpga/fpga-mgr.c
@@ -515,17 +515,17 @@ void fpga_mgr_unlock(struct fpga_manager *mgr)
 EXPORT_SYMBOL_GPL(fpga_mgr_unlock);
 
 /**
- * fpga_mgr_register - register a low level fpga manager driver
+ * fpga_mgr_create - create and initialize a FPGA manager struct
  * @dev:	fpga manager device from pdev
  * @name:	fpga manager name
  * @mops:	pointer to structure of fpga manager ops
  * @priv:	fpga manager private data
  *
- * Return: 0 on success, negative error code otherwise.
+ * Return: pointer to struct fpga_manager or NULL
  */
-int fpga_mgr_register(struct device *dev, const char *name,
-		      const struct fpga_manager_ops *mops,
-		      void *priv)
+struct fpga_manager *fpga_mgr_create(struct device *dev, const char *name,
+				     const struct fpga_manager_ops *mops,
+				     void *priv)
 {
 	struct fpga_manager *mgr;
 	int id, ret;
@@ -534,17 +534,17 @@ int fpga_mgr_register(struct device *dev, const char *name,
 	    !mops->write_init || (!mops->write && !mops->write_sg) ||
 	    (mops->write && mops->write_sg)) {
 		dev_err(dev, "Attempt to register without fpga_manager_ops\n");
-		return -EINVAL;
+		return NULL;
 	}
 
 	if (!name || !strlen(name)) {
 		dev_err(dev, "Attempt to register with no name!\n");
-		return -EINVAL;
+		return NULL;
 	}
 
 	mgr = kzalloc(sizeof(*mgr), GFP_KERNEL);
 	if (!mgr)
-		return -ENOMEM;
+		return NULL;
 
 	id = ida_simple_get(&fpga_mgr_ida, 0, 0, GFP_KERNEL);
 	if (id < 0) {
@@ -558,25 +558,56 @@ int fpga_mgr_register(struct device *dev, const char *name,
 	mgr->mops = mops;
 	mgr->priv = priv;
 
-	/*
-	 * Initialize framework state by requesting low level driver read state
-	 * from device.  FPGA may be in reset mode or may have been programmed
-	 * by bootloader or EEPROM.
-	 */
-	mgr->state = mgr->mops->state(mgr);
-
 	device_initialize(&mgr->dev);
 	mgr->dev.class = fpga_mgr_class;
 	mgr->dev.groups = mops->groups;
 	mgr->dev.parent = dev;
 	mgr->dev.of_node = dev->of_node;
 	mgr->dev.id = id;
-	dev_set_drvdata(dev, mgr);
 
 	ret = dev_set_name(&mgr->dev, "fpga%d", id);
 	if (ret)
 		goto error_device;
 
+	return mgr;
+
+error_device:
+	ida_simple_remove(&fpga_mgr_ida, id);
+error_kfree:
+	kfree(mgr);
+
+	return NULL;
+}
+EXPORT_SYMBOL_GPL(fpga_mgr_create);
+
+/**
+ * fpga_mgr_free - deallocate a FPGA manager
+ * @mgr:	fpga manager struct created by fpga_mgr_create
+ */
+void fpga_mgr_free(struct fpga_manager *mgr)
+{
+	ida_simple_remove(&fpga_mgr_ida, mgr->dev.id);
+	kfree(mgr);
+}
+EXPORT_SYMBOL_GPL(fpga_mgr_free);
+
+/**
+ * fpga_mgr_register - register a FPGA manager
+ * @mgr:	fpga manager struct created by fpga_mgr_create
+ *
+ * Return: 0 on success, negative error code otherwise.
+ */
+int fpga_mgr_register(struct fpga_manager *mgr)
+{
+	int ret;
+
+	/*
+	 * Initialize framework state by requesting low level driver read state
+	 * from device.  FPGA may be in reset mode or may have been programmed
+	 * by bootloader or EEPROM.
+	 */
+	mgr->state = mgr->mops->state(mgr);
+
 	ret = device_add(&mgr->dev);
 	if (ret)
 		goto error_device;
@@ -586,22 +617,18 @@ int fpga_mgr_register(struct device *dev, const char *name,
 	return 0;
 
 error_device:
-	ida_simple_remove(&fpga_mgr_ida, id);
-error_kfree:
-	kfree(mgr);
+	ida_simple_remove(&fpga_mgr_ida, mgr->dev.id);
 
 	return ret;
 }
 EXPORT_SYMBOL_GPL(fpga_mgr_register);
 
 /**
- * fpga_mgr_unregister - unregister a low level fpga manager driver
- * @dev:	fpga manager device from pdev
+ * fpga_mgr_unregister - unregister a FPGA manager
+ * @mgr:	fpga manager struct
  */
-void fpga_mgr_unregister(struct device *dev)
+void fpga_mgr_unregister(struct fpga_manager *mgr)
 {
-	struct fpga_manager *mgr = dev_get_drvdata(dev);
-
 	dev_info(&mgr->dev, "%s %s\n", __func__, mgr->name);
 
 	/*
@@ -619,8 +646,7 @@ static void fpga_mgr_dev_release(struct device *dev)
 {
 	struct fpga_manager *mgr = to_fpga_manager(dev);
 
-	ida_simple_remove(&fpga_mgr_ida, mgr->dev.id);
-	kfree(mgr);
+	fpga_mgr_free(mgr);
 }
 
 static int __init fpga_mgr_class_init(void)
diff --git a/drivers/fpga/ice40-spi.c b/drivers/fpga/ice40-spi.c
index 7fca820..5981c7e 100644
--- a/drivers/fpga/ice40-spi.c
+++ b/drivers/fpga/ice40-spi.c
@@ -133,6 +133,7 @@ static int ice40_fpga_probe(struct spi_device *spi)
 {
 	struct device *dev = &spi->dev;
 	struct ice40_fpga_priv *priv;
+	struct fpga_manager *mgr;
 	int ret;
 
 	priv = devm_kzalloc(&spi->dev, sizeof(*priv), GFP_KERNEL);
@@ -174,14 +175,26 @@ static int ice40_fpga_probe(struct spi_device *spi)
 		return ret;
 	}
 
-	/* Register with the FPGA manager */
-	return fpga_mgr_register(dev, "Lattice iCE40 FPGA Manager",
-				 &ice40_fpga_ops, priv);
+	mgr = fpga_mgr_create(dev, "Lattice iCE40 FPGA Manager",
+			      &ice40_fpga_ops, priv);
+	if (!mgr)
+		return -ENOMEM;
+
+	spi_set_drvdata(spi, mgr);
+
+	ret = fpga_mgr_register(mgr);
+	if (ret)
+		fpga_mgr_free(mgr);
+
+	return ret;
 }
 
 static int ice40_fpga_remove(struct spi_device *spi)
 {
-	fpga_mgr_unregister(&spi->dev);
+	struct fpga_manager *mgr = spi_get_drvdata(spi);
+
+	fpga_mgr_unregister(mgr);
+
 	return 0;
 }
 
diff --git a/drivers/fpga/machxo2-spi.c b/drivers/fpga/machxo2-spi.c
index 8e95ec9..a582e00 100644
--- a/drivers/fpga/machxo2-spi.c
+++ b/drivers/fpga/machxo2-spi.c
@@ -355,21 +355,33 @@ static const struct fpga_manager_ops machxo2_ops = {
 static int machxo2_spi_probe(struct spi_device *spi)
 {
 	struct device *dev = &spi->dev;
+	struct fpga_manager *mgr;
+	int ret;
 
 	if (spi->max_speed_hz > MACHXO2_MAX_SPEED) {
 		dev_err(dev, "Speed is too high\n");
 		return -EINVAL;
 	}
 
-	return fpga_mgr_register(dev, "Lattice MachXO2 SPI FPGA Manager",
-				 &machxo2_ops, spi);
+	mgr = fpga_mgr_create(dev, "Lattice MachXO2 SPI FPGA Manager",
+			      &machxo2_ops, spi);
+	if (!mgr)
+		return -ENOMEM;
+
+	spi_set_drvdata(spi, mgr);
+
+	ret = fpga_mgr_register(mgr);
+	if (ret)
+		fpga_mgr_free(mgr);
+
+	return ret;
 }
 
 static int machxo2_spi_remove(struct spi_device *spi)
 {
-	struct device *dev = &spi->dev;
+	struct fpga_manager *mgr = spi_get_drvdata(spi);
 
-	fpga_mgr_unregister(dev);
+	fpga_mgr_unregister(mgr);
 
 	return 0;
 }
diff --git a/drivers/fpga/socfpga-a10.c b/drivers/fpga/socfpga-a10.c
index a46e343..dec3db5 100644
--- a/drivers/fpga/socfpga-a10.c
+++ b/drivers/fpga/socfpga-a10.c
@@ -482,6 +482,7 @@ static int socfpga_a10_fpga_probe(struct platform_device *pdev)
 	struct device *dev = &pdev->dev;
 	struct a10_fpga_priv *priv;
 	void __iomem *reg_base;
+	struct fpga_manager *mgr;
 	struct resource *res;
 	int ret;
 
@@ -519,9 +520,16 @@ static int socfpga_a10_fpga_probe(struct platform_device *pdev)
 		return -EBUSY;
 	}
 
-	ret = fpga_mgr_register(dev, "SoCFPGA Arria10 FPGA Manager",
-				 &socfpga_a10_fpga_mgr_ops, priv);
+	mgr = fpga_mgr_create(dev, "SoCFPGA Arria10 FPGA Manager",
+			      &socfpga_a10_fpga_mgr_ops, priv);
+	if (!mgr)
+		return -ENOMEM;
+
+	platform_set_drvdata(pdev, mgr);
+
+	ret = fpga_mgr_register(mgr);
 	if (ret) {
+		fpga_mgr_free(mgr);
 		clk_disable_unprepare(priv->clk);
 		return ret;
 	}
@@ -534,7 +542,7 @@ static int socfpga_a10_fpga_remove(struct platform_device *pdev)
 	struct fpga_manager *mgr = platform_get_drvdata(pdev);
 	struct a10_fpga_priv *priv = mgr->priv;
 
-	fpga_mgr_unregister(&pdev->dev);
+	fpga_mgr_unregister(mgr);
 	clk_disable_unprepare(priv->clk);
 
 	return 0;
diff --git a/drivers/fpga/socfpga.c b/drivers/fpga/socfpga.c
index b6672e6..51efaf9 100644
--- a/drivers/fpga/socfpga.c
+++ b/drivers/fpga/socfpga.c
@@ -555,6 +555,7 @@ static int socfpga_fpga_probe(struct platform_device *pdev)
 {
 	struct device *dev = &pdev->dev;
 	struct socfpga_fpga_priv *priv;
+	struct fpga_manager *mgr;
 	struct resource *res;
 	int ret;
 
@@ -581,13 +582,25 @@ static int socfpga_fpga_probe(struct platform_device *pdev)
 	if (ret)
 		return ret;
 
-	return fpga_mgr_register(dev, "Altera SOCFPGA FPGA Manager",
-				 &socfpga_fpga_ops, priv);
+	mgr = fpga_mgr_create(dev, "Altera SOCFPGA FPGA Manager",
+			      &socfpga_fpga_ops, priv);
+	if (!mgr)
+		return -ENOMEM;
+
+	platform_set_drvdata(pdev, mgr);
+
+	ret = fpga_mgr_register(mgr);
+	if (ret)
+		fpga_mgr_free(mgr);
+
+	return ret;
 }
 
 static int socfpga_fpga_remove(struct platform_device *pdev)
 {
-	fpga_mgr_unregister(&pdev->dev);
+	struct fpga_manager *mgr = platform_get_drvdata(pdev);
+
+	fpga_mgr_unregister(mgr);
 
 	return 0;
 }
diff --git a/drivers/fpga/ts73xx-fpga.c b/drivers/fpga/ts73xx-fpga.c
index f6a96b4..08efd18 100644
--- a/drivers/fpga/ts73xx-fpga.c
+++ b/drivers/fpga/ts73xx-fpga.c
@@ -116,7 +116,9 @@ static int ts73xx_fpga_probe(struct platform_device *pdev)
 {
 	struct device *kdev = &pdev->dev;
 	struct ts73xx_fpga_priv *priv;
+	struct fpga_manager *mgr;
 	struct resource *res;
+	int ret;
 
 	priv = devm_kzalloc(kdev, sizeof(*priv), GFP_KERNEL);
 	if (!priv)
@@ -131,13 +133,25 @@ static int ts73xx_fpga_probe(struct platform_device *pdev)
 		return PTR_ERR(priv->io_base);
 	}
 
-	return fpga_mgr_register(kdev, "TS-73xx FPGA Manager",
-				 &ts73xx_fpga_ops, priv);
+	mgr = fpga_mgr_create(kdev, "TS-73xx FPGA Manager",
+			      &ts73xx_fpga_ops, priv);
+	if (!mgr)
+		return -ENOMEM;
+
+	platform_set_drvdata(pdev, mgr);
+
+	ret = fpga_mgr_register(mgr);
+	if (ret)
+		fpga_mgr_free(mgr);
+
+	return ret;
 }
 
 static int ts73xx_fpga_remove(struct platform_device *pdev)
 {
-	fpga_mgr_unregister(&pdev->dev);
+	struct fpga_manager *mgr = platform_get_drvdata(pdev);
+
+	fpga_mgr_unregister(mgr);
 
 	return 0;
 }
diff --git a/drivers/fpga/xilinx-spi.c b/drivers/fpga/xilinx-spi.c
index 9b62a4c..8d19459 100644
--- a/drivers/fpga/xilinx-spi.c
+++ b/drivers/fpga/xilinx-spi.c
@@ -143,6 +143,8 @@ static const struct fpga_manager_ops xilinx_spi_ops = {
 static int xilinx_spi_probe(struct spi_device *spi)
 {
 	struct xilinx_spi_conf *conf;
+	struct fpga_manager *mgr;
+	int ret;
 
 	conf = devm_kzalloc(&spi->dev, sizeof(*conf), GFP_KERNEL);
 	if (!conf)
@@ -165,13 +167,25 @@ static int xilinx_spi_probe(struct spi_device *spi)
 		return PTR_ERR(conf->done);
 	}
 
-	return fpga_mgr_register(&spi->dev, "Xilinx Slave Serial FPGA Manager",
-				 &xilinx_spi_ops, conf);
+	mgr = fpga_mgr_create(&spi->dev, "Xilinx Slave Serial FPGA Manager",
+			      &xilinx_spi_ops, conf);
+	if (!mgr)
+		return -ENOMEM;
+
+	spi_set_drvdata(spi, mgr);
+
+	ret = fpga_mgr_register(mgr);
+	if (ret)
+		fpga_mgr_free(mgr);
+
+	return ret;
 }
 
 static int xilinx_spi_remove(struct spi_device *spi)
 {
-	fpga_mgr_unregister(&spi->dev);
+	struct fpga_manager *mgr = spi_get_drvdata(spi);
+
+	fpga_mgr_unregister(mgr);
 
 	return 0;
 }
diff --git a/drivers/fpga/zynq-fpga.c b/drivers/fpga/zynq-fpga.c
index 70b15b3..3110e00 100644
--- a/drivers/fpga/zynq-fpga.c
+++ b/drivers/fpga/zynq-fpga.c
@@ -558,6 +558,7 @@ static int zynq_fpga_probe(struct platform_device *pdev)
 {
 	struct device *dev = &pdev->dev;
 	struct zynq_fpga_priv *priv;
+	struct fpga_manager *mgr;
 	struct resource *res;
 	int err;
 
@@ -613,10 +614,17 @@ static int zynq_fpga_probe(struct platform_device *pdev)
 
 	clk_disable(priv->clk);
 
-	err = fpga_mgr_register(dev, "Xilinx Zynq FPGA Manager",
-				&zynq_fpga_ops, priv);
+	mgr = fpga_mgr_create(dev, "Xilinx Zynq FPGA Manager",
+			      &zynq_fpga_ops, priv);
+	if (!mgr)
+		return -ENOMEM;
+
+	platform_set_drvdata(pdev, mgr);
+
+	err = fpga_mgr_register(mgr);
 	if (err) {
 		dev_err(dev, "unable to register FPGA manager\n");
+		fpga_mgr_free(mgr);
 		clk_unprepare(priv->clk);
 		return err;
 	}
@@ -632,7 +640,7 @@ static int zynq_fpga_remove(struct platform_device *pdev)
 	mgr = platform_get_drvdata(pdev);
 	priv = mgr->priv;
 
-	fpga_mgr_unregister(&pdev->dev);
+	fpga_mgr_unregister(mgr);
 
 	clk_unprepare(priv->clk);
 
diff --git a/include/linux/fpga/fpga-mgr.h b/include/linux/fpga/fpga-mgr.h
index 3c6de23..1266c11 100644
--- a/include/linux/fpga/fpga-mgr.h
+++ b/include/linux/fpga/fpga-mgr.h
@@ -170,9 +170,11 @@ struct fpga_manager *fpga_mgr_get(struct device *dev);
 
 void fpga_mgr_put(struct fpga_manager *mgr);
 
-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);
+struct fpga_manager *fpga_mgr_create(struct device *dev, const char *name,
+				     const struct fpga_manager_ops *mops,
+				     void *priv);
+void fpga_mgr_free(struct fpga_manager *mgr);
+int fpga_mgr_register(struct fpga_manager *mgr);
+void fpga_mgr_unregister(struct fpga_manager *mgr);
 
 #endif /*_LINUX_FPGA_MGR_H */
-- 
2.7.4

^ permalink raw reply related	[flat|nested] 26+ messages in thread
* [PATCH 03/14] fpga: bridge: change api, don't use drvdata
  2018-05-16 23:49 [PATCH 00/14] fpga api changes and kernel-doc fixup Alan Tull
  2018-05-16 23:49 ` [PATCH 01/14] fpga: region: don't use drvdata in common fpga code Alan Tull
  2018-05-16 23:49 ` [PATCH 02/14] fpga: manager: change api, don't use drvdata Alan Tull
@ 2018-05-16 23:49 ` Alan Tull
  2018-05-16 23:49 ` [PATCH 04/14] fpga: region: change api, add fpga_region_create/free Alan Tull
                   ` (11 subsequent siblings)
  14 siblings, 0 replies; 26+ messages in thread
From: Alan Tull @ 2018-05-16 23:49 UTC (permalink / raw)
  To: Greg Kroah-Hartman, Jonathan Corbet, Moritz Fischer
  Cc: linux-kernel, linux-fpga, Alan Tull

Change fpga_bridge_register to not set drvdata.  This is to support
the case where a PCIe device can have more than one bridge.

Add API functions to create/free the fpga bridge struct. Change
fpga_bridge_register/unregister to take FPGA bridge struct as
the only parameter.

  struct fpga_bridge
  *fpga_bridge_create(struct device *dev, const char *name,
                      const struct fpga_bridge_ops *br_ops,
                      void *priv);
  void fpga_bridge_free(struct fpga_bridge *br);
  int fpga_bridge_register(struct fpga_bridge *br);
  void fpga_bridge_unregister(struct fpga_bridge *br);

Update the drivers that call fpga_bridge_register with the new API.

Signed-off-by: Alan Tull <atull@kernel.org>
Reported-by: Jiuyue Ma <majiuyue@huawei.com>
Signed-off-by: Moritz Fischer <mdf@kernel.org>
---
 drivers/fpga/altera-fpga2sdram.c    | 21 ++++++++---
 drivers/fpga/altera-freeze-bridge.c | 22 ++++++++++--
 drivers/fpga/altera-hps2fpga.c      | 24 ++++++++++---
 drivers/fpga/fpga-bridge.c          | 70 ++++++++++++++++++++++++-------------
 drivers/fpga/xilinx-pr-decoupler.c  | 22 +++++++++---
 include/linux/fpga/fpga-bridge.h    |  9 +++--
 6 files changed, 123 insertions(+), 45 deletions(-)

diff --git a/drivers/fpga/altera-fpga2sdram.c b/drivers/fpga/altera-fpga2sdram.c
index d4eeb74..5a29ab6 100644
--- a/drivers/fpga/altera-fpga2sdram.c
+++ b/drivers/fpga/altera-fpga2sdram.c
@@ -106,6 +106,7 @@ static int alt_fpga_bridge_probe(struct platform_device *pdev)
 {
 	struct device *dev = &pdev->dev;
 	struct alt_fpga2sdram_data *priv;
+	struct fpga_bridge *br;
 	u32 enable;
 	struct regmap *sysmgr;
 	int ret = 0;
@@ -131,10 +132,18 @@ static int alt_fpga_bridge_probe(struct platform_device *pdev)
 	/* Get f2s bridge configuration saved in handoff register */
 	regmap_read(sysmgr, SYSMGR_ISWGRP_HANDOFF3, &priv->mask);
 
-	ret = fpga_bridge_register(dev, F2S_BRIDGE_NAME,
-				   &altera_fpga2sdram_br_ops, priv);
-	if (ret)
+	br = fpga_bridge_create(dev, F2S_BRIDGE_NAME,
+				&altera_fpga2sdram_br_ops, priv);
+	if (!br)
+		return -ENOMEM;
+
+	platform_set_drvdata(pdev, br);
+
+	ret = fpga_bridge_register(br);
+	if (ret) {
+		fpga_bridge_free(br);
 		return ret;
+	}
 
 	dev_info(dev, "driver initialized with handoff %08x\n", priv->mask);
 
@@ -146,7 +155,7 @@ static int alt_fpga_bridge_probe(struct platform_device *pdev)
 				 (enable ? "enabling" : "disabling"));
 			ret = _alt_fpga2sdram_enable_set(priv, enable);
 			if (ret) {
-				fpga_bridge_unregister(&pdev->dev);
+				fpga_bridge_unregister(br);
 				return ret;
 			}
 		}
@@ -157,7 +166,9 @@ static int alt_fpga_bridge_probe(struct platform_device *pdev)
 
 static int alt_fpga_bridge_remove(struct platform_device *pdev)
 {
-	fpga_bridge_unregister(&pdev->dev);
+	struct fpga_bridge *br = platform_get_drvdata(pdev);
+
+	fpga_bridge_unregister(br);
 
 	return 0;
 }
diff --git a/drivers/fpga/altera-freeze-bridge.c b/drivers/fpga/altera-freeze-bridge.c
index 6159cfcf..fa4b693 100644
--- a/drivers/fpga/altera-freeze-bridge.c
+++ b/drivers/fpga/altera-freeze-bridge.c
@@ -221,8 +221,10 @@ static int altera_freeze_br_probe(struct platform_device *pdev)
 	struct device_node *np = pdev->dev.of_node;
 	void __iomem *base_addr;
 	struct altera_freeze_br_data *priv;
+	struct fpga_bridge *br;
 	struct resource *res;
 	u32 status, revision;
+	int ret;
 
 	if (!np)
 		return -ENODEV;
@@ -254,13 +256,27 @@ static int altera_freeze_br_probe(struct platform_device *pdev)
 
 	priv->base_addr = base_addr;
 
-	return fpga_bridge_register(dev, FREEZE_BRIDGE_NAME,
-				    &altera_freeze_br_br_ops, priv);
+	br = fpga_bridge_create(dev, FREEZE_BRIDGE_NAME,
+				&altera_freeze_br_br_ops, priv);
+	if (!br)
+		return -ENOMEM;
+
+	platform_set_drvdata(pdev, br);
+
+	ret = fpga_bridge_register(br);
+	if (ret) {
+		fpga_bridge_free(br);
+		return ret;
+	}
+
+	return 0;
 }
 
 static int altera_freeze_br_remove(struct platform_device *pdev)
 {
-	fpga_bridge_unregister(&pdev->dev);
+	struct fpga_bridge *br = platform_get_drvdata(pdev);
+
+	fpga_bridge_unregister(br);
 
 	return 0;
 }
diff --git a/drivers/fpga/altera-hps2fpga.c b/drivers/fpga/altera-hps2fpga.c
index 406d2f1..e4d39f0 100644
--- a/drivers/fpga/altera-hps2fpga.c
+++ b/drivers/fpga/altera-hps2fpga.c
@@ -139,6 +139,7 @@ static int alt_fpga_bridge_probe(struct platform_device *pdev)
 	struct device *dev = &pdev->dev;
 	struct altera_hps2fpga_data *priv;
 	const struct of_device_id *of_id;
+	struct fpga_bridge *br;
 	u32 enable;
 	int ret;
 
@@ -190,11 +191,24 @@ static int alt_fpga_bridge_probe(struct platform_device *pdev)
 		}
 	}
 
-	ret = fpga_bridge_register(dev, priv->name, &altera_hps2fpga_br_ops,
-				   priv);
-err:
+	br = fpga_bridge_create(dev, priv->name, &altera_hps2fpga_br_ops, priv);
+	if (!br) {
+		ret = -ENOMEM;
+		goto err;
+	}
+
+	platform_set_drvdata(pdev, br);
+
+	ret = fpga_bridge_register(br);
 	if (ret)
-		clk_disable_unprepare(priv->clk);
+		goto err_free;
+
+	return 0;
+
+err_free:
+	fpga_bridge_free(br);
+err:
+	clk_disable_unprepare(priv->clk);
 
 	return ret;
 }
@@ -204,7 +218,7 @@ static int alt_fpga_bridge_remove(struct platform_device *pdev)
 	struct fpga_bridge *bridge = platform_get_drvdata(pdev);
 	struct altera_hps2fpga_data *priv = bridge->priv;
 
-	fpga_bridge_unregister(&pdev->dev);
+	fpga_bridge_unregister(bridge);
 
 	clk_disable_unprepare(priv->clk);
 
diff --git a/drivers/fpga/fpga-bridge.c b/drivers/fpga/fpga-bridge.c
index 31bd2c5..2db1573 100644
--- a/drivers/fpga/fpga-bridge.c
+++ b/drivers/fpga/fpga-bridge.c
@@ -328,28 +328,29 @@ static struct attribute *fpga_bridge_attrs[] = {
 ATTRIBUTE_GROUPS(fpga_bridge);
 
 /**
- * fpga_bridge_register - register a fpga bridge driver
+ * fpga_bridge_create - create and initialize a struct fpga_bridge
  * @dev:	FPGA bridge device from pdev
  * @name:	FPGA bridge name
  * @br_ops:	pointer to structure of fpga bridge ops
  * @priv:	FPGA bridge private data
  *
- * Return: 0 for success, error code otherwise.
+ * Return: struct fpga_bridge or NULL
  */
-int fpga_bridge_register(struct device *dev, const char *name,
-			 const struct fpga_bridge_ops *br_ops, void *priv)
+struct fpga_bridge *fpga_bridge_create(struct device *dev, const char *name,
+				       const struct fpga_bridge_ops *br_ops,
+				       void *priv)
 {
 	struct fpga_bridge *bridge;
 	int id, ret = 0;
 
 	if (!name || !strlen(name)) {
 		dev_err(dev, "Attempt to register with no name!\n");
-		return -EINVAL;
+		return NULL;
 	}
 
 	bridge = kzalloc(sizeof(*bridge), GFP_KERNEL);
 	if (!bridge)
-		return -ENOMEM;
+		return NULL;
 
 	id = ida_simple_get(&fpga_bridge_ida, 0, 0, GFP_KERNEL);
 	if (id < 0) {
@@ -370,40 +371,62 @@ int fpga_bridge_register(struct device *dev, const char *name,
 	bridge->dev.parent = dev;
 	bridge->dev.of_node = dev->of_node;
 	bridge->dev.id = id;
-	dev_set_drvdata(dev, bridge);
 
 	ret = dev_set_name(&bridge->dev, "br%d", id);
 	if (ret)
 		goto error_device;
 
-	ret = device_add(&bridge->dev);
-	if (ret)
-		goto error_device;
-
-	of_platform_populate(dev->of_node, NULL, NULL, dev);
-
-	dev_info(bridge->dev.parent, "fpga bridge [%s] registered\n",
-		 bridge->name);
-
-	return 0;
+	return bridge;
 
 error_device:
 	ida_simple_remove(&fpga_bridge_ida, id);
 error_kfree:
 	kfree(bridge);
 
-	return ret;
+	return NULL;
+}
+EXPORT_SYMBOL_GPL(fpga_bridge_create);
+
+/**
+ * fpga_bridge_free - free a fpga bridge and its id
+ * @bridge:	FPGA bridge struct created by fpga_bridge_create
+ */
+void fpga_bridge_free(struct fpga_bridge *bridge)
+{
+	ida_simple_remove(&fpga_bridge_ida, bridge->dev.id);
+	kfree(bridge);
+}
+EXPORT_SYMBOL_GPL(fpga_bridge_free);
+
+/**
+ * fpga_bridge_register - register a fpga bridge
+ * @bridge:	FPGA bridge struct created by fpga_bridge_create
+ *
+ * Return: 0 for success, error code otherwise.
+ */
+int fpga_bridge_register(struct fpga_bridge *bridge)
+{
+	struct device *dev = &bridge->dev;
+	int ret;
+
+	ret = device_add(dev);
+	if (ret)
+		return ret;
+
+	of_platform_populate(dev->of_node, NULL, NULL, dev);
+
+	dev_info(dev->parent, "fpga bridge [%s] registered\n", bridge->name);
+
+	return 0;
 }
 EXPORT_SYMBOL_GPL(fpga_bridge_register);
 
 /**
  * fpga_bridge_unregister - unregister a fpga bridge driver
- * @dev: FPGA bridge device from pdev
+ * @bridge:	FPGA bridge struct created by fpga_bridge_create
  */
-void fpga_bridge_unregister(struct device *dev)
+void fpga_bridge_unregister(struct fpga_bridge *bridge)
 {
-	struct fpga_bridge *bridge = dev_get_drvdata(dev);
-
 	/*
 	 * If the low level driver provides a method for putting bridge into
 	 * a desired state upon unregister, do it.
@@ -419,8 +442,7 @@ static void fpga_bridge_dev_release(struct device *dev)
 {
 	struct fpga_bridge *bridge = to_fpga_bridge(dev);
 
-	ida_simple_remove(&fpga_bridge_ida, bridge->dev.id);
-	kfree(bridge);
+	fpga_bridge_free(bridge);
 }
 
 static int __init fpga_bridge_dev_init(void)
diff --git a/drivers/fpga/xilinx-pr-decoupler.c b/drivers/fpga/xilinx-pr-decoupler.c
index 0d77430..07ba153 100644
--- a/drivers/fpga/xilinx-pr-decoupler.c
+++ b/drivers/fpga/xilinx-pr-decoupler.c
@@ -94,6 +94,7 @@ MODULE_DEVICE_TABLE(of, xlnx_pr_decoupler_of_match);
 static int xlnx_pr_decoupler_probe(struct platform_device *pdev)
 {
 	struct xlnx_pr_decoupler_data *priv;
+	struct fpga_bridge *br;
 	int err;
 	struct resource *res;
 
@@ -120,16 +121,27 @@ static int xlnx_pr_decoupler_probe(struct platform_device *pdev)
 
 	clk_disable(priv->clk);
 
-	err = fpga_bridge_register(&pdev->dev, "Xilinx PR Decoupler",
-				   &xlnx_pr_decoupler_br_ops, priv);
+	br = fpga_bridge_create(&pdev->dev, "Xilinx PR Decoupler",
+				&xlnx_pr_decoupler_br_ops, priv);
+	if (!br) {
+		err = -ENOMEM;
+		goto err_clk;
+	}
+
+	platform_set_drvdata(pdev, br);
 
+	err = fpga_bridge_register(br);
 	if (err) {
 		dev_err(&pdev->dev, "unable to register Xilinx PR Decoupler");
-		clk_unprepare(priv->clk);
-		return err;
+		goto err_clk;
 	}
 
 	return 0;
+
+err_clk:
+	clk_unprepare(priv->clk);
+
+	return err;
 }
 
 static int xlnx_pr_decoupler_remove(struct platform_device *pdev)
@@ -137,7 +149,7 @@ static int xlnx_pr_decoupler_remove(struct platform_device *pdev)
 	struct fpga_bridge *bridge = platform_get_drvdata(pdev);
 	struct xlnx_pr_decoupler_data *p = bridge->priv;
 
-	fpga_bridge_unregister(&pdev->dev);
+	fpga_bridge_unregister(bridge);
 
 	clk_unprepare(p->clk);
 
diff --git a/include/linux/fpga/fpga-bridge.h b/include/linux/fpga/fpga-bridge.h
index 3694821..ce550fc 100644
--- a/include/linux/fpga/fpga-bridge.h
+++ b/include/linux/fpga/fpga-bridge.h
@@ -62,8 +62,11 @@ int of_fpga_bridge_get_to_list(struct device_node *np,
 			       struct fpga_image_info *info,
 			       struct list_head *bridge_list);
 
-int fpga_bridge_register(struct device *dev, const char *name,
-			 const struct fpga_bridge_ops *br_ops, void *priv);
-void fpga_bridge_unregister(struct device *dev);
+struct fpga_bridge *fpga_bridge_create(struct device *dev, const char *name,
+				       const struct fpga_bridge_ops *br_ops,
+				       void *priv);
+void fpga_bridge_free(struct fpga_bridge *br);
+int fpga_bridge_register(struct fpga_bridge *br);
+void fpga_bridge_unregister(struct fpga_bridge *br);
 
 #endif /* _LINUX_FPGA_BRIDGE_H */
-- 
2.7.4

^ permalink raw reply related	[flat|nested] 26+ messages in thread
* [PATCH 04/14] fpga: region: change api, add fpga_region_create/free
  2018-05-16 23:49 [PATCH 00/14] fpga api changes and kernel-doc fixup Alan Tull
                   ` (2 preceding siblings ...)
  2018-05-16 23:49 ` [PATCH 03/14] fpga: bridge: " Alan Tull
@ 2018-05-16 23:49 ` Alan Tull
  2018-05-16 23:49 ` [PATCH 05/14] fpga: use SPDX Alan Tull
                   ` (10 subsequent siblings)
  14 siblings, 0 replies; 26+ messages in thread
From: Alan Tull @ 2018-05-16 23:49 UTC (permalink / raw)
  To: Greg Kroah-Hartman, Jonathan Corbet, Moritz Fischer
  Cc: linux-kernel, linux-fpga, Alan Tull

Add fpga_region_create/free API functions.

Change fpga_region_register to take FPGA region struct as the only
parameter.  Change fpga_region_unregister to return void.

  struct fpga_region *fpga_region_create(struct device *dev,
                        struct fpga_manager *mgr,
                        int (*get_bridges)(struct fpga_region *));
  void fpga_region_free(struct fpga_region *region);
  int fpga_region_register(struct fpga_region *region);
  void fpga_region_unregister(struct fpga_region *region);

Remove groups storage from struct fpga_region, it's not
needed.  Callers can just "region->dev.groups = groups;"
after calling fpga_region_create.

Update the drivers that call fpga_region_register with the new API.

Signed-off-by: Alan Tull <atull@kernel.org>
Signed-off-by: Moritz Fischer <mdf@kernel.org>
---
 Documentation/fpga/fpga-region.txt |  3 +-
 drivers/fpga/fpga-region.c         | 68 ++++++++++++++++++++++++++++++--------
 drivers/fpga/of-fpga-region.c      | 13 +++-----
 include/linux/fpga/fpga-region.h   | 11 +++---
 4 files changed, 68 insertions(+), 27 deletions(-)

diff --git a/Documentation/fpga/fpga-region.txt b/Documentation/fpga/fpga-region.txt
index 139a02b..d38fa3b 100644
--- a/Documentation/fpga/fpga-region.txt
+++ b/Documentation/fpga/fpga-region.txt
@@ -42,8 +42,7 @@ The FPGA region API
 To register or unregister a region:
 -----------------------------------
 
-	int fpga_region_register(struct device *dev,
-				 struct fpga_region *region);
+	int fpga_region_register(struct fpga_region *region);
 	int fpga_region_unregister(struct fpga_region *region);
 
 An example of usage can be seen in the probe function of [3]
diff --git a/drivers/fpga/fpga-region.c b/drivers/fpga/fpga-region.c
index f634a8e..b3ba3e40 100644
--- a/drivers/fpga/fpga-region.c
+++ b/drivers/fpga/fpga-region.c
@@ -167,18 +167,36 @@ int fpga_region_program_fpga(struct fpga_region *region)
 }
 EXPORT_SYMBOL_GPL(fpga_region_program_fpga);
 
-int fpga_region_register(struct device *dev, struct fpga_region *region)
+/**
+ * fpga_region_create - alloc and init a struct fpga_region
+ * @dev: device parent
+ * @mgr: manager that programs this region
+ * @get_bridges: optional function to get bridges to a list
+ *
+ * Return: struct fpga_region or NULL
+ */
+struct fpga_region
+*fpga_region_create(struct device *dev,
+		    struct fpga_manager *mgr,
+		    int (*get_bridges)(struct fpga_region *))
 {
+	struct fpga_region *region;
 	int id, ret = 0;
 
+	region = kzalloc(sizeof(*region), GFP_KERNEL);
+	if (!region)
+		return NULL;
+
 	id = ida_simple_get(&fpga_region_ida, 0, 0, GFP_KERNEL);
 	if (id < 0)
-		return id;
+		goto err_free;
 
+	region->mgr = mgr;
+	region->get_bridges = get_bridges;
 	mutex_init(&region->mutex);
 	INIT_LIST_HEAD(&region->bridge_list);
+
 	device_initialize(&region->dev);
-	region->dev.groups = region->groups;
 	region->dev.class = fpga_region_class;
 	region->dev.parent = dev;
 	region->dev.of_node = dev->of_node;
@@ -188,23 +206,47 @@ int fpga_region_register(struct device *dev, struct fpga_region *region)
 	if (ret)
 		goto err_remove;
 
-	ret = device_add(&region->dev);
-	if (ret)
-		goto err_remove;
-
-	return 0;
+	return region;
 
 err_remove:
 	ida_simple_remove(&fpga_region_ida, id);
-	return ret;
+err_free:
+	kfree(region);
+
+	return NULL;
+}
+EXPORT_SYMBOL_GPL(fpga_region_create);
+
+/**
+ * fpga_region_free - free a struct fpga_region
+ * @region: FPGA region created by fpga_region_create
+ */
+void fpga_region_free(struct fpga_region *region)
+{
+	ida_simple_remove(&fpga_region_ida, region->dev.id);
+	kfree(region);
+}
+EXPORT_SYMBOL_GPL(fpga_region_free);
+
+/*
+ * fpga_region_register - register a FPGA region
+ * @region: FPGA region created by fpga_region_create
+ * Return: 0 or -errno
+ */
+int fpga_region_register(struct fpga_region *region)
+{
+	return device_add(&region->dev);
+
 }
 EXPORT_SYMBOL_GPL(fpga_region_register);
 
-int fpga_region_unregister(struct fpga_region *region)
+/*
+ * fpga_region_unregister - unregister a FPGA region
+ * @region: FPGA region
+ */
+void fpga_region_unregister(struct fpga_region *region)
 {
 	device_unregister(&region->dev);
-
-	return 0;
 }
 EXPORT_SYMBOL_GPL(fpga_region_unregister);
 
@@ -212,7 +254,7 @@ static void fpga_region_dev_release(struct device *dev)
 {
 	struct fpga_region *region = to_fpga_region(dev);
 
-	ida_simple_remove(&fpga_region_ida, region->dev.id);
+	fpga_region_free(region);
 }
 
 /**
diff --git a/drivers/fpga/of-fpga-region.c b/drivers/fpga/of-fpga-region.c
index 35e7e8c..9d681a1 100644
--- a/drivers/fpga/of-fpga-region.c
+++ b/drivers/fpga/of-fpga-region.c
@@ -422,20 +422,15 @@ static int of_fpga_region_probe(struct platform_device *pdev)
 	if (IS_ERR(mgr))
 		return -EPROBE_DEFER;
 
-	region = devm_kzalloc(dev, sizeof(*region), GFP_KERNEL);
+	region = fpga_region_create(dev, mgr, of_fpga_region_get_bridges);
 	if (!region) {
 		ret = -ENOMEM;
 		goto eprobe_mgr_put;
 	}
 
-	region->mgr = mgr;
-
-	/* Specify how to get bridges for this type of region. */
-	region->get_bridges = of_fpga_region_get_bridges;
-
-	ret = fpga_region_register(dev, region);
+	ret = fpga_region_register(region);
 	if (ret)
-		goto eprobe_mgr_put;
+		goto eprobe_free;
 
 	of_platform_populate(np, fpga_region_of_match, NULL, &region->dev);
 	dev_set_drvdata(dev, region);
@@ -444,6 +439,8 @@ static int of_fpga_region_probe(struct platform_device *pdev)
 
 	return 0;
 
+eprobe_free:
+	fpga_region_free(region);
 eprobe_mgr_put:
 	fpga_mgr_put(mgr);
 	return ret;
diff --git a/include/linux/fpga/fpga-region.h b/include/linux/fpga/fpga-region.h
index b652031..f2e215b 100644
--- a/include/linux/fpga/fpga-region.h
+++ b/include/linux/fpga/fpga-region.h
@@ -14,7 +14,6 @@
  * @info: FPGA image info
  * @priv: private data
  * @get_bridges: optional function to get bridges to a list
- * @groups: optional attribute groups.
  */
 struct fpga_region {
 	struct device dev;
@@ -24,7 +23,6 @@ struct fpga_region {
 	struct fpga_image_info *info;
 	void *priv;
 	int (*get_bridges)(struct fpga_region *region);
-	const struct attribute_group **groups;
 };
 
 #define to_fpga_region(d) container_of(d, struct fpga_region, dev)
@@ -34,7 +32,12 @@ struct fpga_region *fpga_region_class_find(
 	int (*match)(struct device *, const void *));
 
 int fpga_region_program_fpga(struct fpga_region *region);
-int fpga_region_register(struct device *dev, struct fpga_region *region);
-int fpga_region_unregister(struct fpga_region *region);
+
+struct fpga_region
+*fpga_region_create(struct device *dev, struct fpga_manager *mgr,
+		    int (*get_bridges)(struct fpga_region *));
+void fpga_region_free(struct fpga_region *region);
+int fpga_region_register(struct fpga_region *region);
+void fpga_region_unregister(struct fpga_region *region);
 
 #endif /* _FPGA_REGION_H */
-- 
2.7.4

^ permalink raw reply related	[flat|nested] 26+ messages in thread
* [PATCH 05/14] fpga: use SPDX
  2018-05-16 23:49 [PATCH 00/14] fpga api changes and kernel-doc fixup Alan Tull
                   ` (3 preceding siblings ...)
  2018-05-16 23:49 ` [PATCH 04/14] fpga: region: change api, add fpga_region_create/free Alan Tull
@ 2018-05-16 23:49 ` Alan Tull
  2018-05-16 23:49 ` [PATCH 06/14] fpga: mgr: kernel-doc fixes Alan Tull
                   ` (9 subsequent siblings)
  14 siblings, 0 replies; 26+ messages in thread
From: Alan Tull @ 2018-05-16 23:49 UTC (permalink / raw)
  To: Greg Kroah-Hartman, Jonathan Corbet, Moritz Fischer
  Cc: linux-kernel, linux-fpga, Alan Tull

Replace GPLv2 boilerplate with SPDX in FPGA code that came from me or
from Altera.

Signed-off-by: Alan Tull <atull@kernel.org>
---
 drivers/fpga/altera-fpga2sdram.c       | 13 +------------
 drivers/fpga/altera-freeze-bridge.c    | 13 +------------
 drivers/fpga/altera-hps2fpga.c         | 13 +------------
 drivers/fpga/altera-pr-ip-core-plat.c  | 13 +------------
 drivers/fpga/altera-pr-ip-core.c       | 13 +------------
 drivers/fpga/fpga-bridge.c             | 13 +------------
 drivers/fpga/fpga-mgr.c                | 13 +------------
 drivers/fpga/fpga-region.c             | 14 +-------------
 drivers/fpga/of-fpga-region.c          | 14 +-------------
 drivers/fpga/socfpga-a10.c             | 14 +-------------
 drivers/fpga/socfpga.c                 | 13 +------------
 include/linux/fpga/altera-pr-ip-core.h | 13 +------------
 include/linux/fpga/fpga-mgr.h          | 13 +------------
 include/linux/fpga/fpga-region.h       |  2 ++
 14 files changed, 15 insertions(+), 159 deletions(-)

diff --git a/drivers/fpga/altera-fpga2sdram.c b/drivers/fpga/altera-fpga2sdram.c
index 5a29ab6..23660cc 100644
--- a/drivers/fpga/altera-fpga2sdram.c
+++ b/drivers/fpga/altera-fpga2sdram.c
@@ -1,19 +1,8 @@
+// SPDX-License-Identifier: GPL-2.0
 /*
  * FPGA to SDRAM Bridge Driver for Altera SoCFPGA Devices
  *
  *  Copyright (C) 2013-2016 Altera Corporation, All Rights Reserved.
- *
- * This program is free software; you can redistribute it and/or modify it
- * under the terms and conditions of the GNU General Public License,
- * version 2, as published by the Free Software Foundation.
- *
- * This program is distributed in the hope it will be useful, but WITHOUT
- * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
- * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
- * more details.
- *
- * You should have received a copy of the GNU General Public License along with
- * this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
 /*
diff --git a/drivers/fpga/altera-freeze-bridge.c b/drivers/fpga/altera-freeze-bridge.c
index fa4b693..ffd586c 100644
--- a/drivers/fpga/altera-freeze-bridge.c
+++ b/drivers/fpga/altera-freeze-bridge.c
@@ -1,19 +1,8 @@
+// SPDX-License-Identifier: GPL-2.0
 /*
  * FPGA Freeze Bridge Controller
  *
  *  Copyright (C) 2016 Altera Corporation. All rights reserved.
- *
- * This program is free software; you can redistribute it and/or modify it
- * under the terms and conditions of the GNU General Public License,
- * version 2, as published by the Free Software Foundation.
- *
- * This program is distributed in the hope it will be useful, but WITHOUT
- * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
- * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
- * more details.
- *
- * You should have received a copy of the GNU General Public License along with
- * this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 #include <linux/delay.h>
 #include <linux/io.h>
diff --git a/drivers/fpga/altera-hps2fpga.c b/drivers/fpga/altera-hps2fpga.c
index e4d39f0..a974d3f 100644
--- a/drivers/fpga/altera-hps2fpga.c
+++ b/drivers/fpga/altera-hps2fpga.c
@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: GPL-2.0
 /*
  * FPGA to/from HPS Bridge Driver for Altera SoCFPGA Devices
  *
@@ -6,18 +7,6 @@
  * Includes this patch from the mailing list:
  *   fpga: altera-hps2fpga: fix HPS2FPGA bridge visibility to L3 masters
  *   Signed-off-by: Anatolij Gustschin <agust@denx.de>
- *
- * This program is free software; you can redistribute it and/or modify it
- * under the terms and conditions of the GNU General Public License,
- * version 2, as published by the Free Software Foundation.
- *
- * This program is distributed in the hope it will be useful, but WITHOUT
- * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
- * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
- * more details.
- *
- * You should have received a copy of the GNU General Public License along with
- * this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
 /*
diff --git a/drivers/fpga/altera-pr-ip-core-plat.c b/drivers/fpga/altera-pr-ip-core-plat.c
index 8fb36b8..b293d83 100644
--- a/drivers/fpga/altera-pr-ip-core-plat.c
+++ b/drivers/fpga/altera-pr-ip-core-plat.c
@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: GPL-2.0
 /*
  * Driver for Altera Partial Reconfiguration IP Core
  *
@@ -5,18 +6,6 @@
  *
  * Based on socfpga-a10.c Copyright (C) 2015-2016 Altera Corporation
  *  by Alan Tull <atull@opensource.altera.com>
- *
- * This program is free software; you can redistribute it and/or modify it
- * under the terms and conditions of the GNU General Public License,
- * version 2, as published by the Free Software Foundation.
- *
- * This program is distributed in the hope it will be useful, but WITHOUT
- * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
- * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
- * more details.
- *
- * You should have received a copy of the GNU General Public License along with
- * this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 #include <linux/fpga/altera-pr-ip-core.h>
 #include <linux/module.h>
diff --git a/drivers/fpga/altera-pr-ip-core.c b/drivers/fpga/altera-pr-ip-core.c
index eea5217..65e0b6a 100644
--- a/drivers/fpga/altera-pr-ip-core.c
+++ b/drivers/fpga/altera-pr-ip-core.c
@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: GPL-2.0
 /*
  * Driver for Altera Partial Reconfiguration IP Core
  *
@@ -5,18 +6,6 @@
  *
  * Based on socfpga-a10.c Copyright (C) 2015-2016 Altera Corporation
  *  by Alan Tull <atull@opensource.altera.com>
- *
- * This program is free software; you can redistribute it and/or modify it
- * under the terms and conditions of the GNU General Public License,
- * version 2, as published by the Free Software Foundation.
- *
- * This program is distributed in the hope it will be useful, but WITHOUT
- * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
- * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
- * more details.
- *
- * You should have received a copy of the GNU General Public License along with
- * this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 #include <linux/delay.h>
 #include <linux/fpga/altera-pr-ip-core.h>
diff --git a/drivers/fpga/fpga-bridge.c b/drivers/fpga/fpga-bridge.c
index 2db1573..164eb55 100644
--- a/drivers/fpga/fpga-bridge.c
+++ b/drivers/fpga/fpga-bridge.c
@@ -1,20 +1,9 @@
+// SPDX-License-Identifier: GPL-2.0
 /*
  * FPGA Bridge Framework Driver
  *
  *  Copyright (C) 2013-2016 Altera Corporation, All Rights Reserved.
  *  Copyright (C) 2017 Intel Corporation
- *
- * This program is free software; you can redistribute it and/or modify it
- * under the terms and conditions of the GNU General Public License,
- * version 2, as published by the Free Software Foundation.
- *
- * This program is distributed in the hope it will be useful, but WITHOUT
- * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
- * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
- * more details.
- *
- * You should have received a copy of the GNU General Public License along with
- * this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 #include <linux/fpga/fpga-bridge.h>
 #include <linux/idr.h>
diff --git a/drivers/fpga/fpga-mgr.c b/drivers/fpga/fpga-mgr.c
index 0a5181d..151ac36 100644
--- a/drivers/fpga/fpga-mgr.c
+++ b/drivers/fpga/fpga-mgr.c
@@ -1,3 +1,4 @@
+// SPDX-License-Identifier: GPL-2.0
 /*
  * FPGA Manager Core
  *
@@ -6,18 +7,6 @@
  *
  * With code from the mailing list:
  * Copyright (C) 2013 Xilinx, Inc.
- *
- * This program is free software; you can redistribute it and/or modify it
- * under the terms and conditions of the GNU General Public License,
- * version 2, as published by the Free Software Foundation.
- *
- * This program is distributed in the hope it will be useful, but WITHOUT
- * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
- * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
- * more details.
- *
- * You should have received a copy of the GNU General Public License along with
- * this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 #include <linux/firmware.h>
 #include <linux/fpga/fpga-mgr.h>
diff --git a/drivers/fpga/fpga-region.c b/drivers/fpga/fpga-region.c
index b3ba3e40..0878f62 100644
--- a/drivers/fpga/fpga-region.c
+++ b/drivers/fpga/fpga-region.c
@@ -1,22 +1,10 @@
+// SPDX-License-Identifier: GPL-2.0
 /*
  * FPGA Region - Device Tree support for FPGA programming under Linux
  *
  *  Copyright (C) 2013-2016 Altera Corporation
  *  Copyright (C) 2017 Intel Corporation
- *
- * This program is free software; you can redistribute it and/or modify it
- * under the terms and conditions of the GNU General Public License,
- * version 2, as published by the Free Software Foundation.
- *
- * This program is distributed in the hope it will be useful, but WITHOUT
- * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
- * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
- * more details.
- *
- * You should have received a copy of the GNU General Public License along with
- * this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
 #include <linux/fpga/fpga-bridge.h>
 #include <linux/fpga/fpga-mgr.h>
 #include <linux/fpga/fpga-region.h>
diff --git a/drivers/fpga/of-fpga-region.c b/drivers/fpga/of-fpga-region.c
index 9d681a1..35fabb8 100644
--- a/drivers/fpga/of-fpga-region.c
+++ b/drivers/fpga/of-fpga-region.c
@@ -1,22 +1,10 @@
+// SPDX-License-Identifier: GPL-2.0
 /*
  * FPGA Region - Device Tree support for FPGA programming under Linux
  *
  *  Copyright (C) 2013-2016 Altera Corporation
  *  Copyright (C) 2017 Intel Corporation
- *
- * This program is free software; you can redistribute it and/or modify it
- * under the terms and conditions of the GNU General Public License,
- * version 2, as published by the Free Software Foundation.
- *
- * This program is distributed in the hope it will be useful, but WITHOUT
- * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
- * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
- * more details.
- *
- * You should have received a copy of the GNU General Public License along with
- * this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
 #include <linux/fpga/fpga-bridge.h>
 #include <linux/fpga/fpga-mgr.h>
 #include <linux/fpga/fpga-region.h>
diff --git a/drivers/fpga/socfpga-a10.c b/drivers/fpga/socfpga-a10.c
index dec3db5..be30c48 100644
--- a/drivers/fpga/socfpga-a10.c
+++ b/drivers/fpga/socfpga-a10.c
@@ -1,21 +1,9 @@
+// SPDX-License-Identifier: GPL-2.0
 /*
  * FPGA Manager Driver for Altera Arria10 SoCFPGA
  *
  * Copyright (C) 2015-2016 Altera Corporation
- *
- * This program is free software; you can redistribute it and/or modify it
- * under the terms and conditions of the GNU General Public License,
- * version 2, as published by the Free Software Foundation.
- *
- * This program is distributed in the hope it will be useful, but WITHOUT
- * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
- * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
- * more details.
- *
- * You should have received a copy of the GNU General Public License along with
- * this program.  If not, see <http://www.gnu.org/licenses/>.
  */
-
 #include <linux/clk.h>
 #include <linux/device.h>
 #include <linux/delay.h>
diff --git a/drivers/fpga/socfpga.c b/drivers/fpga/socfpga.c
index 51efaf9..959d71f 100644
--- a/drivers/fpga/socfpga.c
+++ b/drivers/fpga/socfpga.c
@@ -1,19 +1,8 @@
+// SPDX-License-Identifier: GPL-2.0
 /*
  * FPGA Manager Driver for Altera SOCFPGA
  *
  *  Copyright (C) 2013-2015 Altera Corporation
- *
- * This program is free software; you can redistribute it and/or modify it
- * under the terms and conditions of the GNU General Public License,
- * version 2, as published by the Free Software Foundation.
- *
- * This program is distributed in the hope it will be useful, but WITHOUT
- * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
- * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
- * more details.
- *
- * You should have received a copy of the GNU General Public License along with
- * this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 #include <linux/completion.h>
 #include <linux/delay.h>
diff --git a/include/linux/fpga/altera-pr-ip-core.h b/include/linux/fpga/altera-pr-ip-core.h
index 3810a90..7d46647 100644
--- a/include/linux/fpga/altera-pr-ip-core.h
+++ b/include/linux/fpga/altera-pr-ip-core.h
@@ -1,3 +1,4 @@
+/* SPDX-License-Identifier: GPL-2.0 */
 /*
  * Driver for Altera Partial Reconfiguration IP Core
  *
@@ -5,18 +6,6 @@
  *
  * Based on socfpga-a10.c Copyright (C) 2015-2016 Altera Corporation
  *  by Alan Tull <atull@opensource.altera.com>
- *
- * This program is free software; you can redistribute it and/or modify it
- * under the terms and conditions of the GNU General Public License,
- * version 2, as published by the Free Software Foundation.
- *
- * This program is distributed in the hope it will be useful, but WITHOUT
- * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
- * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
- * more details.
- *
- * You should have received a copy of the GNU General Public License along with
- * this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
 #ifndef _ALT_PR_IP_CORE_H
diff --git a/include/linux/fpga/fpga-mgr.h b/include/linux/fpga/fpga-mgr.h
index 1266c11..eec7c24 100644
--- a/include/linux/fpga/fpga-mgr.h
+++ b/include/linux/fpga/fpga-mgr.h
@@ -1,20 +1,9 @@
+/* SPDX-License-Identifier: GPL-2.0 */
 /*
  * FPGA Framework
  *
  *  Copyright (C) 2013-2016 Altera Corporation
  *  Copyright (C) 2017 Intel Corporation
- *
- * This program is free software; you can redistribute it and/or modify it
- * under the terms and conditions of the GNU General Public License,
- * version 2, as published by the Free Software Foundation.
- *
- * This program is distributed in the hope it will be useful, but WITHOUT
- * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
- * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
- * more details.
- *
- * You should have received a copy of the GNU General Public License along with
- * this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 #ifndef _LINUX_FPGA_MGR_H
 #define _LINUX_FPGA_MGR_H
diff --git a/include/linux/fpga/fpga-region.h b/include/linux/fpga/fpga-region.h
index f2e215b..d7071cd 100644
--- a/include/linux/fpga/fpga-region.h
+++ b/include/linux/fpga/fpga-region.h
@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: GPL-2.0 */
+
 #ifndef _FPGA_REGION_H
 #define _FPGA_REGION_H
 
-- 
2.7.4

^ permalink raw reply related	[flat|nested] 26+ messages in thread
* [PATCH 06/14] fpga: mgr: kernel-doc fixes
  2018-05-16 23:49 [PATCH 00/14] fpga api changes and kernel-doc fixup Alan Tull
                   ` (4 preceding siblings ...)
  2018-05-16 23:49 ` [PATCH 05/14] fpga: use SPDX Alan Tull
@ 2018-05-16 23:49 ` Alan Tull
  2018-05-23 17:14   ` Moritz Fischer
                     ` (2 more replies)
  2018-05-16 23:50 ` [PATCH 07/14] fpga: bridge: " Alan Tull
                   ` (8 subsequent siblings)
  14 siblings, 3 replies; 26+ messages in thread
From: Alan Tull @ 2018-05-16 23:49 UTC (permalink / raw)
  To: Greg Kroah-Hartman, Jonathan Corbet, Moritz Fischer
  Cc: linux-kernel, linux-fpga, Alan Tull

Clean up the kernel-doc documentation in fpga-mgr.c and fix the
following warnings when documentation is built:

./drivers/fpga/fpga-mgr.c:252: warning: Function parameter or member
'info' not described in 'fpga_mgr_buf_load'

./drivers/fpga/fpga-mgr.c:252: warning: Excess function parameter
'flags' description in 'fpga_mgr_buf_load'

Signed-off-by: Alan Tull <atull@kernel.org>
---
 drivers/fpga/fpga-mgr.c | 38 +++++++++++++++++++++++++++++---------
 1 file changed, 29 insertions(+), 9 deletions(-)

diff --git a/drivers/fpga/fpga-mgr.c b/drivers/fpga/fpga-mgr.c
index 151ac36..5fffeef 100644
--- a/drivers/fpga/fpga-mgr.c
+++ b/drivers/fpga/fpga-mgr.c
@@ -21,6 +21,12 @@
 static DEFINE_IDA(fpga_mgr_ida);
 static struct class *fpga_mgr_class;
 
+/**
+ * fpga_image_info_alloc - Allocate a FPGA image info struct
+ * @dev: owning device
+ *
+ * Return: struct fpga_image_info or NULL
+ */
 struct fpga_image_info *fpga_image_info_alloc(struct device *dev)
 {
 	struct fpga_image_info *info;
@@ -39,6 +45,10 @@ struct fpga_image_info *fpga_image_info_alloc(struct device *dev)
 }
 EXPORT_SYMBOL_GPL(fpga_image_info_alloc);
 
+/**
+ * fpga_image_info_free - Free a FPGA image info struct
+ * @info: FPGA image info struct to free
+ */
 void fpga_image_info_free(struct fpga_image_info *info)
 {
 	struct device *dev;
@@ -223,7 +233,7 @@ static int fpga_mgr_buf_load_mapped(struct fpga_manager *mgr,
 /**
  * fpga_mgr_buf_load - load fpga from image in buffer
  * @mgr:	fpga manager
- * @flags:	flags setting fpga confuration modes
+ * @info:	fpga image info
  * @buf:	buffer contain fpga image
  * @count:	byte count of buf
  *
@@ -332,6 +342,16 @@ static int fpga_mgr_firmware_load(struct fpga_manager *mgr,
 	return ret;
 }
 
+/**
+ * fpga_mgr_load - load FPGA from scatter/gather table, buffer, or firmware
+ * @mgr:	fpga manager
+ * @info:	fpga image information.
+ *
+ * Load the FPGA from an image which is indicated in @info.  If successful, the
+ * FPGA ends up in operating mode.
+ *
+ * Return: 0 on success, negative error code otherwise.
+ */
 int fpga_mgr_load(struct fpga_manager *mgr, struct fpga_image_info *info)
 {
 	if (info->sgt)
@@ -418,11 +438,9 @@ static int fpga_mgr_dev_match(struct device *dev, const void *data)
 }
 
 /**
- * fpga_mgr_get - get a reference to a fpga mgr
+ * fpga_mgr_get - Given a device, get a reference to a fpga mgr.
  * @dev:	parent device that fpga mgr was registered with
  *
- * Given a device, get a reference to a fpga mgr.
- *
  * Return: fpga manager struct or IS_ERR() condition containing error code.
  */
 struct fpga_manager *fpga_mgr_get(struct device *dev)
@@ -442,10 +460,9 @@ static int fpga_mgr_of_node_match(struct device *dev, const void *data)
 }
 
 /**
- * of_fpga_mgr_get - get a reference to a fpga mgr
- * @node:	device node
+ * of_fpga_mgr_get - Given a device node, get a reference to a fpga mgr.
  *
- * Given a device node, get a reference to a fpga mgr.
+ * @node:	device node
  *
  * Return: fpga manager struct or IS_ERR() condition containing error code.
  */
@@ -478,7 +495,10 @@ EXPORT_SYMBOL_GPL(fpga_mgr_put);
  * @mgr:	fpga manager
  *
  * Given a pointer to FPGA Manager (from fpga_mgr_get() or
- * of_fpga_mgr_put()) attempt to get the mutex.
+ * of_fpga_mgr_put()) attempt to get the mutex. The user should call
+ * fpga_mgr_lock() and verify that it returns 0 before attempting to
+ * program the FPGA.  Likewise, the user should call fpga_mgr_unlock
+ * when done programming the FPGA.
  *
  * Return: 0 for success or -EBUSY
  */
@@ -494,7 +514,7 @@ int fpga_mgr_lock(struct fpga_manager *mgr)
 EXPORT_SYMBOL_GPL(fpga_mgr_lock);
 
 /**
- * fpga_mgr_unlock - Unlock FPGA manager
+ * fpga_mgr_unlock - Unlock FPGA manager after done programming
  * @mgr:	fpga manager
  */
 void fpga_mgr_unlock(struct fpga_manager *mgr)
-- 
2.7.4

^ permalink raw reply related	[flat|nested] 26+ messages in thread
* [PATCH 07/14] fpga: bridge: kernel-doc fixes
  2018-05-16 23:49 [PATCH 00/14] fpga api changes and kernel-doc fixup Alan Tull
                   ` (5 preceding siblings ...)
  2018-05-16 23:49 ` [PATCH 06/14] fpga: mgr: kernel-doc fixes Alan Tull
@ 2018-05-16 23:50 ` Alan Tull
  2018-05-24 17:08   ` Moritz Fischer
  2018-05-16 23:50 ` [PATCH 08/14] fpga: region: " Alan Tull
                   ` (7 subsequent siblings)
  14 siblings, 1 reply; 26+ messages in thread
From: Alan Tull @ 2018-05-16 23:50 UTC (permalink / raw)
  To: Greg Kroah-Hartman, Jonathan Corbet, Moritz Fischer
  Cc: linux-kernel, linux-fpga, Alan Tull

Fix the following warnings when documentation is built:

./drivers/fpga/fpga-bridge.c:143: warning: Function parameter or
member 'info' not described in 'fpga_bridge_get'

./drivers/fpga/fpga-bridge.c:1: warning: no structured comments found

Signed-off-by: Alan Tull <atull@kernel.org>
---
 drivers/fpga/fpga-bridge.c | 1 +
 1 file changed, 1 insertion(+)

diff --git a/drivers/fpga/fpga-bridge.c b/drivers/fpga/fpga-bridge.c
index 164eb55..4b207a7 100644
--- a/drivers/fpga/fpga-bridge.c
+++ b/drivers/fpga/fpga-bridge.c
@@ -121,6 +121,7 @@ static int fpga_bridge_dev_match(struct device *dev, const void *data)
 /**
  * fpga_bridge_get - get an exclusive reference to a fpga bridge
  * @dev:	parent device that fpga bridge was registered with
+ * @info:	fpga manager info
  *
  * Given a device, get an exclusive reference to a fpga bridge.
  *
-- 
2.7.4

^ permalink raw reply related	[flat|nested] 26+ messages in thread
* [PATCH 08/14] fpga: region: kernel-doc fixes
  2018-05-16 23:49 [PATCH 00/14] fpga api changes and kernel-doc fixup Alan Tull
                   ` (6 preceding siblings ...)
  2018-05-16 23:50 ` [PATCH 07/14] fpga: bridge: " Alan Tull
@ 2018-05-16 23:50 ` Alan Tull
  2018-05-24 17:09   ` Moritz Fischer
  2018-05-16 23:50 ` [PATCH 09/14] Documentation: fpga: move fpga overview to driver-api Alan Tull
                   ` (6 subsequent siblings)
  14 siblings, 1 reply; 26+ messages in thread
From: Alan Tull @ 2018-05-16 23:50 UTC (permalink / raw)
  To: Greg Kroah-Hartman, Jonathan Corbet, Moritz Fischer
  Cc: linux-kernel, linux-fpga, Alan Tull

Fix formatting and some cleanup for the kernel-doc documentation in
fpga-region.c

Signed-off-by: Alan Tull <atull@kernel.org>
---
 drivers/fpga/fpga-region.c | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/drivers/fpga/fpga-region.c b/drivers/fpga/fpga-region.c
index 0878f62..112fa3a 100644
--- a/drivers/fpga/fpga-region.c
+++ b/drivers/fpga/fpga-region.c
@@ -81,13 +81,16 @@ static void fpga_region_put(struct fpga_region *region)
 
 /**
  * fpga_region_program_fpga - program FPGA
+ *
  * @region: FPGA region
+ *
  * Program an FPGA using fpga image info (region->info).
  * If the region has a get_bridges function, the exclusive reference for the
  * bridges will be held if programming succeeds.  This is intended to prevent
  * reprogramming the region until the caller considers it safe to do so.
  * The caller will need to call fpga_bridges_put() before attempting to
  * reprogram the region.
+ *
  * Return 0 for success or negative error code.
  */
 int fpga_region_program_fpga(struct fpga_region *region)
@@ -216,7 +219,7 @@ void fpga_region_free(struct fpga_region *region)
 }
 EXPORT_SYMBOL_GPL(fpga_region_free);
 
-/*
+/**
  * fpga_region_register - register a FPGA region
  * @region: FPGA region created by fpga_region_create
  * Return: 0 or -errno
@@ -228,7 +231,7 @@ int fpga_region_register(struct fpga_region *region)
 }
 EXPORT_SYMBOL_GPL(fpga_region_register);
 
-/*
+/**
  * fpga_region_unregister - unregister a FPGA region
  * @region: FPGA region
  */
-- 
2.7.4

^ permalink raw reply related	[flat|nested] 26+ messages in thread
* [PATCH 09/14] Documentation: fpga: move fpga overview to driver-api
  2018-05-16 23:49 [PATCH 00/14] fpga api changes and kernel-doc fixup Alan Tull
                   ` (7 preceding siblings ...)
  2018-05-16 23:50 ` [PATCH 08/14] fpga: region: " Alan Tull
@ 2018-05-16 23:50 ` Alan Tull
  2018-05-26  2:21   ` Randy Dunlap
  2018-05-16 23:50 ` [PATCH 10/14] documentation: fpga: move fpga-mgr.txt " Alan Tull
                   ` (5 subsequent siblings)
  14 siblings, 1 reply; 26+ messages in thread
From: Alan Tull @ 2018-05-16 23:50 UTC (permalink / raw)
  To: Greg Kroah-Hartman, Jonathan Corbet, Moritz Fischer
  Cc: linux-kernel, linux-fpga, Alan Tull

Start of moving Documentation/fpga/*.txt to driver-api, including:
 - Add new directory driver-api/fpga
 - Add new file driver-api/fpga/index.rst
 - Add driver-api/fpga to driver-api/index.rst
 - Move Documentation/fpga/overview.txt to driver-api/fpga/intro.rst
 - Formatting and rewrites so that intro.rst will build cleanly
   and form a good introduction to the rest of the docs to be added.

Signed-off-by: Alan Tull <atull@kernel.org>
---
 Documentation/driver-api/fpga/index.rst | 10 ++++++
 Documentation/driver-api/fpga/intro.rst | 54 +++++++++++++++++++++++++++++++++
 Documentation/driver-api/index.rst      |  1 +
 Documentation/fpga/overview.txt         | 23 --------------
 4 files changed, 65 insertions(+), 23 deletions(-)
 create mode 100644 Documentation/driver-api/fpga/index.rst
 create mode 100644 Documentation/driver-api/fpga/intro.rst
 delete mode 100644 Documentation/fpga/overview.txt

diff --git a/Documentation/driver-api/fpga/index.rst b/Documentation/driver-api/fpga/index.rst
new file mode 100644
index 0000000..71e568a
--- /dev/null
+++ b/Documentation/driver-api/fpga/index.rst
@@ -0,0 +1,10 @@
+==============
+FPGA Subsystem
+==============
+
+:Author: Alan Tull
+
+.. toctree::
+   :maxdepth: 2
+
+   intro
diff --git a/Documentation/driver-api/fpga/intro.rst b/Documentation/driver-api/fpga/intro.rst
new file mode 100644
index 0000000..51cd81d
--- /dev/null
+++ b/Documentation/driver-api/fpga/intro.rst
@@ -0,0 +1,54 @@
+Introduction
+============
+
+The FPGA subsystem supports reprogramming FPGAs dynamically under
+Linux.  Some of the core intentions of the FPGA subsystems are:
+
+* The FPGA subsystem is vendor agnostic.
+
+* The FPGA subsystem separates upper layers (userspace interfaces and
+  enumeration) from lower layers that know how to program a specific
+  FPGA.
+
+* Code should not be shared between upper and lower layers.  This
+  should go without saying.  If that seems necessary, there's probably
+  framework functionality that that can be added that will benefit
+  other users.  Write the linux-fpga mailing list and maintainers and
+  seek out a solution that expands the framework for broad reuse.
+
+* Generally, when adding code, think of the future.  Plan for re-use.
+
+The framework in the kernel is divided into:
+
+FPGA Manager
+------------
+
+If you are adding a new FPGA or a new method of programming a FPGA,
+this is the subsystem for you.  Low level FPGA manager drivers contain
+the knowledge of how to program a specific device.  This subsystem
+includes the framework in fpga-mgr.c and the low level drivers that
+are registered with it.
+
+FPGA Bridge
+-----------
+
+FPGA Bridges prevent spurious signals from going out of a FPGA or a
+region of a FPGA during programming.  They are disabled before
+programming begins and re-enabled afterwards.  An FPGA bridge may be
+actual hard hardware that gates a bus to a cpu or a soft ("freeze")
+bridge in FPGA fabric that surrounds a partial reconfiguration region
+of an FPGA.  This subsystem includes fpga-bridge.c and the low level
+drivers that are registered with it.
+
+FPGA Region
+-----------
+
+If you are adding a new interface to the FPGA framework, add it on top
+of a FPGA region to allow the most reuse of your interface.
+
+The FPGA Region framework (fpga-region.c) associates managers and
+bridges as reconfigurable regions.  A region may refer to the whole
+FPGA in full reconfiguration or to a partial reconfiguration region.
+
+The Device Tree FPGA Region support (of-fpga-region.c) handles
+reprogramming FPGAs when device tree overlays are applied.
diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index 7b12b6b..6d9f2f9 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -52,6 +52,7 @@ available subsections can be seen below.
    dmaengine/index
    slimbus
    soundwire/index
+   fpga/index
 
 .. only::  subproject and html
 
diff --git a/Documentation/fpga/overview.txt b/Documentation/fpga/overview.txt
deleted file mode 100644
index 0f1236e..0000000
--- a/Documentation/fpga/overview.txt
+++ /dev/null
@@ -1,23 +0,0 @@
-Linux kernel FPGA support
-
-Alan Tull 2017
-
-The main point of this project has been to separate the out the upper layers
-that know when to reprogram a FPGA from the lower layers that know how to
-reprogram a specific FPGA device.  The intention is to make this manufacturer
-agnostic, understanding that of course the FPGA images are very device specific
-themselves.
-
-The framework in the kernel includes:
-* low level FPGA manager drivers that know how to program a specific device
-* the fpga-mgr framework they are registered with
-* low level FPGA bridge drivers for hard/soft bridges which are intended to
-  be disable during FPGA programming
-* the fpga-bridge framework they are registered with
-* the fpga-region framework which associates and controls managers and bridges
-  as reconfigurable regions
-* the of-fpga-region support for reprogramming FPGAs when device tree overlays
-  are applied.
-
-I would encourage you the user to add code that creates FPGA regions rather
-that trying to control managers and bridges separately.
-- 
2.7.4

^ permalink raw reply related	[flat|nested] 26+ messages in thread
* [PATCH 10/14] documentation: fpga: move fpga-mgr.txt to driver-api
  2018-05-16 23:49 [PATCH 00/14] fpga api changes and kernel-doc fixup Alan Tull
                   ` (8 preceding siblings ...)
  2018-05-16 23:50 ` [PATCH 09/14] Documentation: fpga: move fpga overview to driver-api Alan Tull
@ 2018-05-16 23:50 ` Alan Tull
  2018-05-26  2:29   ` Randy Dunlap
  2018-05-16 23:50 ` [PATCH 11/14] documentation: fpga: add bridge document " Alan Tull
                   ` (4 subsequent siblings)
  14 siblings, 1 reply; 26+ messages in thread
From: Alan Tull @ 2018-05-16 23:50 UTC (permalink / raw)
  To: Greg Kroah-Hartman, Jonathan Corbet, Moritz Fischer
  Cc: linux-kernel, linux-fpga, Alan Tull

Move Documentation/fpga/fpga-mgr.txt to driver-api/fpga/fpga-mgr.rst
and:
 - Add to driver-api/fpga/index.rst
 - Format changes so documentation builds cleanly.
 - Minor rewrites that make the doc flow better as ReST documentation.
   - Such as moving API reference to end of doc
 - Change API reference section to refer to kernel-doc documentation in
   fpga-mgr.c driver code rather than statically defining each function.

Signed-off-by: Alan Tull <atull@kernel.org>
---
 Documentation/driver-api/fpga/fpga-mgr.rst | 220 +++++++++++++++++++++++++++++
 Documentation/driver-api/fpga/index.rst    |   1 +
 Documentation/fpga/fpga-mgr.txt            | 218 ----------------------------
 3 files changed, 221 insertions(+), 218 deletions(-)
 create mode 100644 Documentation/driver-api/fpga/fpga-mgr.rst
 delete mode 100644 Documentation/fpga/fpga-mgr.txt

diff --git a/Documentation/driver-api/fpga/fpga-mgr.rst b/Documentation/driver-api/fpga/fpga-mgr.rst
new file mode 100644
index 0000000..bcf2dd2
--- /dev/null
+++ b/Documentation/driver-api/fpga/fpga-mgr.rst
@@ -0,0 +1,220 @@
+FPGA Manager
+============
+
+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.
+
+The FPGA image to be programmed can be in a scatter gather list, a single
+contiguous buffer, or a firmware file.  Because allocating contiguous kernel
+memory for the buffer should be avoided, users are encouraged to use a scatter
+gather list instead if possible.
+
+The particulars for programming the image are presented in a structure (struct
+fpga_image_info).  This struct contains parameters such as pointers to the
+FPGA image as well as image-specific particulars such as whether the image was
+built for full or partial reconfiguration.
+
+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;
+		struct fpga_manager *mgr;
+		int ret;
+
+		priv = devm_kzalloc(dev, sizeof(*priv), GFP_KERNEL);
+		if (!priv)
+			return -ENOMEM;
+
+		/*
+		 * do ioremaps, get interrupts, etc. and save
+		 * them in priv
+		 */
+
+		mgr = fpga_mgr_create(dev, "Altera SOCFPGA FPGA Manager",
+				      &socfpga_fpga_ops, priv);
+		if (!mgr)
+			return -ENOMEM;
+
+		platform_set_drvdata(pdev, mgr);
+
+		ret = fpga_mgr_register(mgr);
+		if (ret)
+			fpga_mgr_free(mgr);
+
+		return ret;
+	}
+
+	static int socfpga_fpga_remove(struct platform_device *pdev)
+	{
+		struct fpga_manager *mgr = platform_get_drvdata(pdev);
+
+		fpga_mgr_unregister(mgr);
+
+		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 or .write_sg (may be called once or multiple times)
+ 3. .write_complete
+
+The .write_init function will prepare the FPGA to receive the image data.  The
+buffer passed into .write_init will be atmost .initial_header_size bytes long,
+if the whole bitstream is not immediately available then the core code will
+buffer up at least this much before starting.
+
+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. This interface
+is suitable for drivers which use PIO.
+
+The .write_sg version behaves the same as .write except the input is a sg_table
+scatter list. This interface is suitable for drivers which use DMA.
+
+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.
+
+How to write an image buffer to a supported FPGA
+------------------------------------------------
+
+Some sample code::
+
+	#include <linux/fpga/fpga-mgr.h>
+
+	struct fpga_manager *mgr;
+	struct fpga_image_info *info;
+	int ret;
+
+	/*
+	 * Get a reference to FPGA manager.  The manager is not locked, so you can
+	 * hold onto this reference without it preventing programming.
+	 *
+	 * This example uses the device node of the manager.  Alternatively, use
+	 * fpga_mgr_get(dev) instead if you have the device.
+	 */
+	mgr = of_fpga_mgr_get(mgr_node);
+
+	/* struct with information about the FPGA image to program. */
+	info = fpga_image_info_alloc(dev);
+
+	/* flags indicates whether to do full or partial reconfiguration */
+	info->flags = FPGA_MGR_PARTIAL_RECONFIG;
+
+	/*
+	 * At this point, indicate where the image is. This is pseudo-code; you're
+	 * going to use one of these three.
+	 */
+	if (image is in a scatter gather table) {
+
+		info->sgt = [your scatter gather table]
+
+	} else if (image is in a buffer) {
+
+		info->buf = [your image buffer]
+		info->count = [image buffer size]
+
+	} else if (image is in a firmware file) {
+
+		info->firmware_name = devm_kstrdup(dev, firmware_name, GFP_KERNEL);
+
+	}
+
+	/* Get exclusive control of FPGA manager */
+	ret = fpga_mgr_lock(mgr);
+
+	/* Load the buffer to the FPGA */
+	ret = fpga_mgr_buf_load(mgr, &info, buf, count);
+
+	/* Release the FPGA manager */
+	fpga_mgr_unlock(mgr);
+	fpga_mgr_put(mgr);
+
+	/* Deallocate the image info if you're done with it */
+	fpga_image_info_free(info);
+
+API for implementing a new FPGA Manager driver
+----------------------------------------------
+
+.. kernel-doc:: include/linux/fpga/fpga-mgr.h
+   :functions: fpga_manager
+
+.. kernel-doc:: include/linux/fpga/fpga-mgr.h
+   :functions: fpga_manager_ops
+
+.. kernel-doc:: drivers/fpga/fpga-mgr.c
+   :functions: fpga_mgr_create
+
+.. kernel-doc:: drivers/fpga/fpga-mgr.c
+   :functions: fpga_mgr_free
+
+.. kernel-doc:: drivers/fpga/fpga-mgr.c
+   :functions: fpga_mgr_register
+
+.. kernel-doc:: drivers/fpga/fpga-mgr.c
+   :functions: fpga_mgr_unregister
+
+API for programming a FPGA
+--------------------------
+
+.. kernel-doc:: include/linux/fpga/fpga-mgr.h
+   :functions: fpga_image_info
+
+.. kernel-doc:: include/linux/fpga/fpga-mgr.h
+   :functions: fpga_mgr_states
+
+.. kernel-doc:: drivers/fpga/fpga-mgr.c
+   :functions: fpga_image_info_alloc
+
+.. kernel-doc:: drivers/fpga/fpga-mgr.c
+   :functions: fpga_image_info_free
+
+.. kernel-doc:: drivers/fpga/fpga-mgr.c
+   :functions: of_fpga_mgr_get
+
+.. kernel-doc:: drivers/fpga/fpga-mgr.c
+   :functions: fpga_mgr_get
+
+.. kernel-doc:: drivers/fpga/fpga-mgr.c
+   :functions: fpga_mgr_put
+
+.. kernel-doc:: drivers/fpga/fpga-mgr.c
+   :functions: fpga_mgr_lock
+
+.. kernel-doc:: drivers/fpga/fpga-mgr.c
+   :functions: fpga_mgr_unlock
+
+.. kernel-doc:: include/linux/fpga/fpga-mgr.h
+   :functions: fpga_mgr_states
+
+Note - use :c:func:`fpga_region_program_fpga()` instead of :c:func:`fpga_mgr_load()`
+
+.. kernel-doc:: drivers/fpga/fpga-mgr.c
+   :functions: fpga_mgr_load
diff --git a/Documentation/driver-api/fpga/index.rst b/Documentation/driver-api/fpga/index.rst
index 71e568a..34b2075 100644
--- a/Documentation/driver-api/fpga/index.rst
+++ b/Documentation/driver-api/fpga/index.rst
@@ -8,3 +8,4 @@ FPGA Subsystem
    :maxdepth: 2
 
    intro
+   fpga-mgr
diff --git a/Documentation/fpga/fpga-mgr.txt b/Documentation/fpga/fpga-mgr.txt
deleted file mode 100644
index 86b6df6..0000000
--- a/Documentation/fpga/fpga-mgr.txt
+++ /dev/null
@@ -1,218 +0,0 @@
-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.
-
-The FPGA image to be programmed can be in a scatter gather list, a single
-contiguous buffer, or a firmware file.  Because allocating contiguous kernel
-memory for the buffer should be avoided, users are encouraged to use a scatter
-gather list instead if possible.
-
-The particulars for programming the image are presented in a structure (struct
-fpga_image_info).  This struct contains parameters such as pointers to the
-FPGA image as well as image-specific particulars such as whether the image was
-built for full or partial reconfiguration.
-
-API Functions:
-==============
-
-To program the FPGA:
---------------------
-
-	int fpga_mgr_load(struct fpga_manager *mgr,
-			  struct fpga_image_info *info);
-
-Load the FPGA from an image which is indicated in the info.  If successful,
-the FPGA ends up in operating mode.  Return 0 on success or a negative error
-code.
-
-To allocate or free a struct fpga_image_info:
----------------------------------------------
-
-	struct fpga_image_info *fpga_image_info_alloc(struct device *dev);
-
-	void fpga_image_info_free(struct fpga_image_info *info);
-
-To get/put a reference to a FPGA manager:
------------------------------------------
-
-	struct fpga_manager *of_fpga_mgr_get(struct device_node *node);
-	struct fpga_manager *fpga_mgr_get(struct device *dev);
-	void fpga_mgr_put(struct fpga_manager *mgr);
-
-Given a DT node or device, get a reference to a FPGA manager.  This pointer
-can be saved until you are ready to program the FPGA.  fpga_mgr_put releases
-the reference.
-
-
-To get exclusive control of a FPGA manager:
--------------------------------------------
-
-	int fpga_mgr_lock(struct fpga_manager *mgr);
-	void fpga_mgr_unlock(struct fpga_manager *mgr);
-
-The user should call fpga_mgr_lock and verify that it returns 0 before
-attempting to program the FPGA.  Likewise, the user should call
-fpga_mgr_unlock when done programming the FPGA.
-
-To alloc/free a FPGA manager struct:
-------------------------------------
-
-	struct fpga_manager *fpga_mgr_create(struct device *dev,
-					     const char *name,
-					     const struct fpga_manager_ops *mops,
-					     void *priv);
-	void fpga_mgr_free(struct fpga_manager *mgr);
-
-To register or unregister the low level FPGA-specific driver:
--------------------------------------------------------------
-
-	int fpga_mgr_register(struct fpga_manager *mgr);
-
-	void fpga_mgr_unregister(struct fpga_manager *mgr);
-
-Use of these functions is described below in "How To Support a new FPGA
-device."
-
-
-How to write an image buffer to a supported FPGA
-================================================
-#include <linux/fpga/fpga-mgr.h>
-
-struct fpga_manager *mgr;
-struct fpga_image_info *info;
-int ret;
-
-/*
- * Get a reference to FPGA manager.  The manager is not locked, so you can
- * hold onto this reference without it preventing programming.
- *
- * This example uses the device node of the manager.  Alternatively, use
- * fpga_mgr_get(dev) instead if you have the device.
- */
-mgr = of_fpga_mgr_get(mgr_node);
-
-/* struct with information about the FPGA image to program. */
-info = fpga_image_info_alloc(dev);
-
-/* flags indicates whether to do full or partial reconfiguration */
-info->flags = FPGA_MGR_PARTIAL_RECONFIG;
-
-/*
- * At this point, indicate where the image is. This is pseudo-code; you're
- * going to use one of these three.
- */
-if (image is in a scatter gather table) {
-
-	info->sgt = [your scatter gather table]
-
-} else if (image is in a buffer) {
-
-	info->buf = [your image buffer]
-	info->count = [image buffer size]
-
-} else if (image is in a firmware file) {
-
-	info->firmware_name = devm_kstrdup(dev, firmware_name, GFP_KERNEL);
-
-}
-
-/* Get exclusive control of FPGA manager */
-ret = fpga_mgr_lock(mgr);
-
-/* Load the buffer to the FPGA */
-ret = fpga_mgr_buf_load(mgr, &info, buf, count);
-
-/* Release the FPGA manager */
-fpga_mgr_unlock(mgr);
-fpga_mgr_put(mgr);
-
-/* Deallocate the image info if you're done with it */
-fpga_image_info_free(info);
-
-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;
-	struct fpga_manager *mgr;
-	int ret;
-
-	priv = devm_kzalloc(dev, sizeof(*priv), GFP_KERNEL);
-	if (!priv)
-		return -ENOMEM;
-
-	/* ... do ioremaps, get interrupts, etc. and save
-	   them in priv... */
-
-	mgr = fpga_mgr_create(dev, "Altera SOCFPGA FPGA Manager",
-			      &socfpga_fpga_ops, priv);
-	if (!mgr)
-		return -ENOMEM;
-
-	platform_set_drvdata(pdev, mgr);
-
-	ret = fpga_mgr_register(mgr);
-	if (ret)
-		fpga_mgr_free(mgr);
-
-	return ret;
-}
-
-static int socfpga_fpga_remove(struct platform_device *pdev)
-{
-	struct fpga_manager *mgr = platform_get_drvdata(pdev);
-
-	fpga_mgr_unregister(mgr);
-
-	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 or .write_sg (may be called once or multiple times)
- 3. .write_complete
-
-The .write_init function will prepare the FPGA to receive the image data.  The
-buffer passed into .write_init will be atmost .initial_header_size bytes long,
-if the whole bitstream is not immediately available then the core code will
-buffer up at least this much before starting.
-
-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. This interface
-is suitable for drivers which use PIO.
-
-The .write_sg version behaves the same as .write except the input is a sg_table
-scatter list. This interface is suitable for drivers which use DMA.
-
-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.
-- 
2.7.4

^ permalink raw reply related	[flat|nested] 26+ messages in thread
* [PATCH 11/14] documentation: fpga: add bridge document to driver-api
  2018-05-16 23:49 [PATCH 00/14] fpga api changes and kernel-doc fixup Alan Tull
                   ` (9 preceding siblings ...)
  2018-05-16 23:50 ` [PATCH 10/14] documentation: fpga: move fpga-mgr.txt " Alan Tull
@ 2018-05-16 23:50 ` Alan Tull
  2018-05-16 23:50 ` [PATCH 12/14] documentation: fpga: move fpga-region.txt " Alan Tull
                   ` (3 subsequent siblings)
  14 siblings, 0 replies; 26+ messages in thread
From: Alan Tull @ 2018-05-16 23:50 UTC (permalink / raw)
  To: Greg Kroah-Hartman, Jonathan Corbet, Moritz Fischer
  Cc: linux-kernel, linux-fpga, Alan Tull

Add a new document to driver-api/fpga that documents the
fpga bridge API and add it to driver-api/fpga/index.rst

Signed-off-by: Alan Tull <atull@kernel.org>
---
 Documentation/driver-api/fpga/fpga-bridge.rst | 49 +++++++++++++++++++++++++++
 Documentation/driver-api/fpga/index.rst       |  1 +
 2 files changed, 50 insertions(+)
 create mode 100644 Documentation/driver-api/fpga/fpga-bridge.rst

diff --git a/Documentation/driver-api/fpga/fpga-bridge.rst b/Documentation/driver-api/fpga/fpga-bridge.rst
new file mode 100644
index 0000000..2c2aaca
--- /dev/null
+++ b/Documentation/driver-api/fpga/fpga-bridge.rst
@@ -0,0 +1,49 @@
+FPGA Bridge
+===========
+
+API to implement a new FPGA bridge
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. kernel-doc:: include/linux/fpga/fpga-bridge.h
+   :functions: fpga_bridge
+
+.. kernel-doc:: include/linux/fpga/fpga-bridge.h
+   :functions: fpga_bridge_ops
+
+.. kernel-doc:: drivers/fpga/fpga-bridge.c
+   :functions: fpga_bridge_create
+
+.. kernel-doc:: drivers/fpga/fpga-bridge.c
+   :functions: fpga_bridge_free
+
+.. kernel-doc:: drivers/fpga/fpga-bridge.c
+   :functions: fpga_bridge_register
+
+.. kernel-doc:: drivers/fpga/fpga-bridge.c
+   :functions: fpga_bridge_unregister
+
+API to control an FPGA bridge
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You probably won't need these directly.  FPGA regions should handle this.
+
+.. kernel-doc:: drivers/fpga/fpga-bridge.c
+   :functions: of_fpga_bridge_get
+
+.. kernel-doc:: drivers/fpga/fpga-bridge.c
+   :functions: fpga_bridge_get
+
+.. kernel-doc:: drivers/fpga/fpga-bridge.c
+   :functions: fpga_bridge_put
+
+.. kernel-doc:: drivers/fpga/fpga-bridge.c
+   :functions: fpga_bridge_get_to_list
+
+.. kernel-doc:: drivers/fpga/fpga-bridge.c
+   :functions: of_fpga_bridge_get_to_list
+
+.. kernel-doc:: drivers/fpga/fpga-bridge.c
+   :functions: fpga_bridge_enable
+
+.. kernel-doc:: drivers/fpga/fpga-bridge.c
+   :functions: fpga_bridge_disable
diff --git a/Documentation/driver-api/fpga/index.rst b/Documentation/driver-api/fpga/index.rst
index 34b2075..968bbbf 100644
--- a/Documentation/driver-api/fpga/index.rst
+++ b/Documentation/driver-api/fpga/index.rst
@@ -9,3 +9,4 @@ FPGA Subsystem
 
    intro
    fpga-mgr
+   fpga-bridge
-- 
2.7.4

^ permalink raw reply related	[flat|nested] 26+ messages in thread
* [PATCH 12/14] documentation: fpga: move fpga-region.txt to driver-api
  2018-05-16 23:49 [PATCH 00/14] fpga api changes and kernel-doc fixup Alan Tull
                   ` (10 preceding siblings ...)
  2018-05-16 23:50 ` [PATCH 11/14] documentation: fpga: add bridge document " Alan Tull
@ 2018-05-16 23:50 ` Alan Tull
  2018-05-26  2:33   ` Randy Dunlap
  2018-05-16 23:50 ` [PATCH 13/14] fpga: clarify that unregister functions also free Alan Tull
                   ` (2 subsequent siblings)
  14 siblings, 1 reply; 26+ messages in thread
From: Alan Tull @ 2018-05-16 23:50 UTC (permalink / raw)
  To: Greg Kroah-Hartman, Jonathan Corbet, Moritz Fischer
  Cc: linux-kernel, linux-fpga, Alan Tull

Move Documentation/fpga/fpga-region.txt to
driver-api/fpga/fpga-region.rst.  Including:
 - Add it to driver-api/fpga/index.rst
 - Formatting changes to build cleanly as ReST documentation
 - Some rewrites for better flow as a ReST doc such as moving
   API reference to the end of the doc
 - Rewrite API reference section to refer to kernel-doc
   documentation in fpga-region.c driver code

Signed-off-by: Alan Tull <atull@kernel.org>
---
 Documentation/driver-api/fpga/fpga-region.rst | 102 ++++++++++++++++++++++++++
 Documentation/driver-api/fpga/index.rst       |   1 +
 Documentation/fpga/fpga-region.txt            |  94 ------------------------
 3 files changed, 103 insertions(+), 94 deletions(-)
 create mode 100644 Documentation/driver-api/fpga/fpga-region.rst
 delete mode 100644 Documentation/fpga/fpga-region.txt

diff --git a/Documentation/driver-api/fpga/fpga-region.rst b/Documentation/driver-api/fpga/fpga-region.rst
new file mode 100644
index 0000000..f89e4a3
--- /dev/null
+++ b/Documentation/driver-api/fpga/fpga-region.rst
@@ -0,0 +1,102 @@
+FPGA Region
+===========
+
+Overview
+--------
+
+This document is meant to be an brief overview of the FPGA region API usage.  A
+more conceptual look at regions can be found in the Device Tree binding
+document [#f1]_.
+
+For the purposes of this API document, let's just say that a region associates
+an FPGA Manager and a bridge (or bridges) with a reprogrammable region of an
+FPGA or the whole FPGA.  The API provides a way to register a region and to
+program a region.
+
+Currently the only layer above fpga-region.c in the kernel is the Device Tree
+support (of-fpga-region.c) described in [#f1]_.  The DT support layer uses regions
+to program the FPGA and then DT to handle enumeration.  The common region code
+is intended to be used by other schemes that have other ways of accomplishing
+enumeration after programming.
+
+An fpga-region can be set up to know the following things:
+
+ * which FPGA manager to use to do the programming
+
+ * which bridges to disable before programming and enable afterwards.
+
+Additional info needed to program the FPGA image is passed in the struct
+fpga_image_info including:
+
+ * pointers to the image as either a scatter-gather buffer, a contiguous
+   buffer, or the name of firmware file
+
+ * flags indicating specifics such as whether the image if for partial
+   reconfiguration.
+
+How to program a FPGA using a region
+------------------------------------
+
+First, allocate the info struct::
+
+	info = fpga_image_info_alloc(dev);
+	if (!info)
+		return -ENOMEM;
+
+Set flags as needed, i.e.::
+
+	info->flags |= FPGA_MGR_PARTIAL_RECONFIG;
+
+Point to your FPGA image, such as::
+
+	info->sgt = &sgt;
+
+Add info to region and do the programming::
+
+	region->info = info;
+	ret = fpga_region_program_fpga(region);
+
+:c:func:`fpga_region_program_fpga()` operates on info passed in the
+fpga_image_info (region->info).  This function will attempt to:
+
+ * lock the region's mutex
+ * lock the region's FPGA manager
+ * build a list of FPGA bridges if a method has been specified to do so
+ * disable the bridges
+ * program the FPGA
+ * re-enable the bridges
+ * release the locks
+
+Then you will want to enumerate whatever hardware has appeared in the FPGA.
+
+How to add a new FPGA region
+----------------------------
+
+An example of usage can be seen in the probe function of [#f2]_.
+
+.. [#f1] ../devicetree/bindings/fpga/fpga-region.txt
+.. [#f2] ../../drivers/fpga/of-fpga-region.c
+
+API to program a FGPA
+---------------------
+
+.. kernel-doc:: drivers/fpga/fpga-region.c
+   :functions: fpga_region_program_fpga
+
+API to add a new FPGA region
+----------------------------
+
+.. kernel-doc:: include/linux/fpga/fpga-region.h
+   :functions: fpga_region
+
+.. kernel-doc:: drivers/fpga/fpga-region.c
+   :functions: fpga_region_create
+
+.. kernel-doc:: drivers/fpga/fpga-region.c
+   :functions: fpga_region_free
+
+.. kernel-doc:: drivers/fpga/fpga-region.c
+   :functions: fpga_region_register
+
+.. kernel-doc:: drivers/fpga/fpga-region.c
+   :functions: fpga_region_unregister
diff --git a/Documentation/driver-api/fpga/index.rst b/Documentation/driver-api/fpga/index.rst
index 968bbbf..c51e5eb 100644
--- a/Documentation/driver-api/fpga/index.rst
+++ b/Documentation/driver-api/fpga/index.rst
@@ -10,3 +10,4 @@ FPGA Subsystem
    intro
    fpga-mgr
    fpga-bridge
+   fpga-region
diff --git a/Documentation/fpga/fpga-region.txt b/Documentation/fpga/fpga-region.txt
deleted file mode 100644
index d38fa3b..0000000
--- a/Documentation/fpga/fpga-region.txt
+++ /dev/null
@@ -1,94 +0,0 @@
-FPGA Regions
-
-Alan Tull 2017
-
-CONTENTS
- - Introduction
- - The FPGA region API
- - Usage example
-
-Introduction
-============
-
-This document is meant to be an brief overview of the FPGA region API usage.  A
-more conceptual look at regions can be found in [1].
-
-For the purposes of this API document, let's just say that a region associates
-an FPGA Manager and a bridge (or bridges) with a reprogrammable region of an
-FPGA or the whole FPGA.  The API provides a way to register a region and to
-program a region.
-
-Currently the only layer above fpga-region.c in the kernel is the Device Tree
-support (of-fpga-region.c) described in [1].  The DT support layer uses regions
-to program the FPGA and then DT to handle enumeration.  The common region code
-is intended to be used by other schemes that have other ways of accomplishing
-enumeration after programming.
-
-An fpga-region can be set up to know the following things:
-* which FPGA manager to use to do the programming
-* which bridges to disable before programming and enable afterwards.
-
-Additional info needed to program the FPGA image is passed in the struct
-fpga_image_info [2] including:
-* pointers to the image as either a scatter-gather buffer, a contiguous
-  buffer, or the name of firmware file
-* flags indicating specifics such as whether the image if for partial
-  reconfiguration.
-
-===================
-The FPGA region API
-===================
-
-To register or unregister a region:
------------------------------------
-
-	int fpga_region_register(struct fpga_region *region);
-	int fpga_region_unregister(struct fpga_region *region);
-
-An example of usage can be seen in the probe function of [3]
-
-To program an FPGA:
--------------------
-	int fpga_region_program_fpga(struct fpga_region *region);
-
-This function operates on info passed in the fpga_image_info
-(region->info).
-
-This function will attempt to:
- * lock the region's mutex
- * lock the region's FPGA manager
- * build a list of FPGA bridges if a method has been specified to do so
- * disable the bridges
- * program the FPGA
- * re-enable the bridges
- * release the locks
-
-=============
-Usage example
-=============
-
-First, allocate the info struct:
-
-	info = fpga_image_info_alloc(dev);
-	if (!info)
-		return -ENOMEM;
-
-Set flags as needed, i.e.
-
-	info->flags |= FPGA_MGR_PARTIAL_RECONFIG;
-
-Point to your FPGA image, such as:
-
-	info->sgt = &sgt;
-
-Add info to region and do the programming:
-
-	region->info = info;
-	ret = fpga_region_program_fpga(region);
-
-Then enumerate whatever hardware has appeared in the FPGA.
-
---
-[1] ../devicetree/bindings/fpga/fpga-region.txt
-[2] ./fpga-mgr.txt
-[3] ../../drivers/fpga/of-fpga-region.c
-- 
2.7.4

^ permalink raw reply related	[flat|nested] 26+ messages in thread
* [PATCH 13/14] fpga: clarify that unregister functions also free
  2018-05-16 23:49 [PATCH 00/14] fpga api changes and kernel-doc fixup Alan Tull
                   ` (11 preceding siblings ...)
  2018-05-16 23:50 ` [PATCH 12/14] documentation: fpga: move fpga-region.txt " Alan Tull
@ 2018-05-16 23:50 ` Alan Tull
  2018-05-16 23:50 ` [PATCH 14/14] MAINTAINERS: Add driver-api/fpga path Alan Tull
  2018-05-17  7:04 ` [PATCH 00/14] fpga api changes and kernel-doc fixup Greg Kroah-Hartman
  14 siblings, 0 replies; 26+ messages in thread
From: Alan Tull @ 2018-05-16 23:50 UTC (permalink / raw)
  To: Greg Kroah-Hartman, Jonathan Corbet, Moritz Fischer
  Cc: linux-kernel, linux-fpga, Alan Tull

The following functions also free the struct.  Add that
fact to the function documentation.
 - fpga_mgr_free
 - fpga_bridge_free
 - fpga_region_free

Signed-off-by: Alan Tull <atull@kernel.org>
---
 drivers/fpga/fpga-bridge.c | 2 +-
 drivers/fpga/fpga-mgr.c    | 2 +-
 drivers/fpga/fpga-region.c | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/drivers/fpga/fpga-bridge.c b/drivers/fpga/fpga-bridge.c
index 4b207a7..24b8f98 100644
--- a/drivers/fpga/fpga-bridge.c
+++ b/drivers/fpga/fpga-bridge.c
@@ -412,7 +412,7 @@ int fpga_bridge_register(struct fpga_bridge *bridge)
 EXPORT_SYMBOL_GPL(fpga_bridge_register);
 
 /**
- * fpga_bridge_unregister - unregister a fpga bridge driver
+ * fpga_bridge_unregister - unregister and free a fpga bridge
  * @bridge:	FPGA bridge struct created by fpga_bridge_create
  */
 void fpga_bridge_unregister(struct fpga_bridge *bridge)
diff --git a/drivers/fpga/fpga-mgr.c b/drivers/fpga/fpga-mgr.c
index 5fffeef..c1564cf 100644
--- a/drivers/fpga/fpga-mgr.c
+++ b/drivers/fpga/fpga-mgr.c
@@ -633,7 +633,7 @@ int fpga_mgr_register(struct fpga_manager *mgr)
 EXPORT_SYMBOL_GPL(fpga_mgr_register);
 
 /**
- * fpga_mgr_unregister - unregister a FPGA manager
+ * fpga_mgr_unregister - unregister and free a FPGA manager
  * @mgr:	fpga manager struct
  */
 void fpga_mgr_unregister(struct fpga_manager *mgr)
diff --git a/drivers/fpga/fpga-region.c b/drivers/fpga/fpga-region.c
index 112fa3a..6d214d7 100644
--- a/drivers/fpga/fpga-region.c
+++ b/drivers/fpga/fpga-region.c
@@ -232,7 +232,7 @@ int fpga_region_register(struct fpga_region *region)
 EXPORT_SYMBOL_GPL(fpga_region_register);
 
 /**
- * fpga_region_unregister - unregister a FPGA region
+ * fpga_region_unregister - unregister and free a FPGA region
  * @region: FPGA region
  */
 void fpga_region_unregister(struct fpga_region *region)
-- 
2.7.4

^ permalink raw reply related	[flat|nested] 26+ messages in thread
* [PATCH 14/14] MAINTAINERS: Add driver-api/fpga path
  2018-05-16 23:49 [PATCH 00/14] fpga api changes and kernel-doc fixup Alan Tull
                   ` (12 preceding siblings ...)
  2018-05-16 23:50 ` [PATCH 13/14] fpga: clarify that unregister functions also free Alan Tull
@ 2018-05-16 23:50 ` Alan Tull
  2018-05-17  7:04 ` [PATCH 00/14] fpga api changes and kernel-doc fixup Greg Kroah-Hartman
  14 siblings, 0 replies; 26+ messages in thread
From: Alan Tull @ 2018-05-16 23:50 UTC (permalink / raw)
  To: Greg Kroah-Hartman, Jonathan Corbet, Moritz Fischer
  Cc: linux-kernel, linux-fpga, Alan Tull

Add Documentation/driver-api/fpga path to MAINTAINERS file
for fpga.

Signed-off-by: Alan Tull <atull@kernel.org>
---
 MAINTAINERS | 1 +
 1 file changed, 1 insertion(+)

diff --git a/MAINTAINERS b/MAINTAINERS
index 9ce5062..febeecd 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -5612,6 +5612,7 @@ S:	Maintained
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/atull/linux-fpga.git
 Q:	http://patchwork.kernel.org/project/linux-fpga/list/
 F:	Documentation/fpga/
+F:	Documentation/driver-api/fpga/
 F:	Documentation/devicetree/bindings/fpga/
 F:	drivers/fpga/
 F:	include/linux/fpga/
-- 
2.7.4

^ permalink raw reply related	[flat|nested] 26+ messages in thread
* Re: [PATCH 00/14] fpga api changes and kernel-doc fixup
  2018-05-16 23:49 [PATCH 00/14] fpga api changes and kernel-doc fixup Alan Tull
                   ` (13 preceding siblings ...)
  2018-05-16 23:50 ` [PATCH 14/14] MAINTAINERS: Add driver-api/fpga path Alan Tull
@ 2018-05-17  7:04 ` Greg Kroah-Hartman
  2018-05-17 14:08   ` Alan Tull
  14 siblings, 1 reply; 26+ messages in thread
From: Greg Kroah-Hartman @ 2018-05-17  7:04 UTC (permalink / raw)
  To: Alan Tull; +Cc: Jonathan Corbet, Moritz Fischer, linux-kernel, linux-fpga

On Wed, May 16, 2018 at 06:49:53PM -0500, Alan Tull wrote:
> I'm posting these all together because they are interdependent.
> 
> Patches 1-4 are a repost of v4 of the FPGA api change.
> 
> Patch 5 is a repost of adding SPDX to my fpga code
> 
> Patch 6-12 update the fpga kernel-doc documentation and move
> existing .txt fpga documentation to driver-api ReST documents.
> 
> Patch 13 is a minor documentation fix
> 
> Patch 14 updates MAINTAINERS for the new driver-api/fpga directory

Are these just for review, or do you feel they are good enough for me to
queue up for 4.18-rc1 now?

thanks,

greg k-h

^ permalink raw reply	[flat|nested] 26+ messages in thread
* Re: [PATCH 00/14] fpga api changes and kernel-doc fixup
  2018-05-17  7:04 ` [PATCH 00/14] fpga api changes and kernel-doc fixup Greg Kroah-Hartman
@ 2018-05-17 14:08   ` Alan Tull
  0 siblings, 0 replies; 26+ messages in thread
From: Alan Tull @ 2018-05-17 14:08 UTC (permalink / raw)
  To: Greg Kroah-Hartman
  Cc: Jonathan Corbet, Moritz Fischer, linux-kernel, linux-fpga

On Thu, May 17, 2018 at 2:04 AM, Greg Kroah-Hartman
<gregkh@linuxfoundation.org> wrote:
> On Wed, May 16, 2018 at 06:49:53PM -0500, Alan Tull wrote:
>> I'm posting these all together because they are interdependent.
>>
>> Patches 1-4 are a repost of v4 of the FPGA api change.
>>
>> Patch 5 is a repost of adding SPDX to my fpga code
>>
>> Patch 6-12 update the fpga kernel-doc documentation and move
>> existing .txt fpga documentation to driver-api ReST documents.
>>
>> Patch 13 is a minor documentation fix
>>
>> Patch 14 updates MAINTAINERS for the new driver-api/fpga directory
>
> Are these just for review, or do you feel they are good enough for me to
> queue up for 4.18-rc1 now?

I think the first five are good to go, but that's your call.

Patches 1-4 are the API reworked following your suggestions.

Patch 5 (SPDX) = I haven't heard any feedback on, but I think it's good.

So I think patches 1-5 are good (if you agree).  The rest are new to
the mailing list and haven't been reviewed/acked by anybody else yet.

I generally avoid posting reviewed/unreviewed patches together, sorry.
I just didn't want to open the possibility of patches being applied
out of order and the issues that can cause.

Alan

>
> thanks,
>
> greg k-h

^ permalink raw reply	[flat|nested] 26+ messages in thread
* Re: [PATCH 06/14] fpga: mgr: kernel-doc fixes
  2018-05-16 23:49 ` [PATCH 06/14] fpga: mgr: kernel-doc fixes Alan Tull
@ 2018-05-23 17:14   ` Moritz Fischer
  2018-05-23 17:15   ` Moritz Fischer
  2018-05-24 17:07   ` Moritz Fischer
  2 siblings, 0 replies; 26+ messages in thread
From: Moritz Fischer @ 2018-05-23 17:14 UTC (permalink / raw)
  To: Alan Tull
  Cc: Greg Kroah-Hartman, Jonathan Corbet, Moritz Fischer,
	linux-kernel, linux-fpga

On Wed, May 16, 2018 at 06:49:59PM -0500, Alan Tull wrote:
> Clean up the kernel-doc documentation in fpga-mgr.c and fix the
> following warnings when documentation is built:
> 
> ./drivers/fpga/fpga-mgr.c:252: warning: Function parameter or member
> 'info' not described in 'fpga_mgr_buf_load'
> 
> ./drivers/fpga/fpga-mgr.c:252: warning: Excess function parameter
> 'flags' description in 'fpga_mgr_buf_load'
> 
> Signed-off-by: Alan Tull <atull@kernel.org>
Acked-by: Moritz Fischer <mdf@kernel.org>
> ---
>  drivers/fpga/fpga-mgr.c | 38 +++++++++++++++++++++++++++++---------
>  1 file changed, 29 insertions(+), 9 deletions(-)
> 
> diff --git a/drivers/fpga/fpga-mgr.c b/drivers/fpga/fpga-mgr.c
> index 151ac36..5fffeef 100644
> --- a/drivers/fpga/fpga-mgr.c
> +++ b/drivers/fpga/fpga-mgr.c
> @@ -21,6 +21,12 @@
>  static DEFINE_IDA(fpga_mgr_ida);
>  static struct class *fpga_mgr_class;
>  
> +/**
> + * fpga_image_info_alloc - Allocate a FPGA image info struct
> + * @dev: owning device
> + *
> + * Return: struct fpga_image_info or NULL
> + */
>  struct fpga_image_info *fpga_image_info_alloc(struct device *dev)
>  {
>  	struct fpga_image_info *info;
> @@ -39,6 +45,10 @@ struct fpga_image_info *fpga_image_info_alloc(struct device *dev)
>  }
>  EXPORT_SYMBOL_GPL(fpga_image_info_alloc);
>  
> +/**
> + * fpga_image_info_free - Free a FPGA image info struct
> + * @info: FPGA image info struct to free
> + */
>  void fpga_image_info_free(struct fpga_image_info *info)
>  {
>  	struct device *dev;
> @@ -223,7 +233,7 @@ static int fpga_mgr_buf_load_mapped(struct fpga_manager *mgr,
>  /**
>   * fpga_mgr_buf_load - load fpga from image in buffer
>   * @mgr:	fpga manager
> - * @flags:	flags setting fpga confuration modes
> + * @info:	fpga image info
>   * @buf:	buffer contain fpga image
>   * @count:	byte count of buf
>   *
> @@ -332,6 +342,16 @@ static int fpga_mgr_firmware_load(struct fpga_manager *mgr,
>  	return ret;
>  }
>  
> +/**
> + * fpga_mgr_load - load FPGA from scatter/gather table, buffer, or firmware
> + * @mgr:	fpga manager
> + * @info:	fpga image information.
> + *
> + * Load the FPGA from an image which is indicated in @info.  If successful, the
> + * FPGA ends up in operating mode.
> + *
> + * Return: 0 on success, negative error code otherwise.
> + */
>  int fpga_mgr_load(struct fpga_manager *mgr, struct fpga_image_info *info)
>  {
>  	if (info->sgt)
> @@ -418,11 +438,9 @@ static int fpga_mgr_dev_match(struct device *dev, const void *data)
>  }
>  
>  /**
> - * fpga_mgr_get - get a reference to a fpga mgr
> + * fpga_mgr_get - Given a device, get a reference to a fpga mgr.
>   * @dev:	parent device that fpga mgr was registered with
>   *
> - * Given a device, get a reference to a fpga mgr.
> - *
>   * Return: fpga manager struct or IS_ERR() condition containing error code.
>   */
>  struct fpga_manager *fpga_mgr_get(struct device *dev)
> @@ -442,10 +460,9 @@ static int fpga_mgr_of_node_match(struct device *dev, const void *data)
>  }
>  
>  /**
> - * of_fpga_mgr_get - get a reference to a fpga mgr
> - * @node:	device node
> + * of_fpga_mgr_get - Given a device node, get a reference to a fpga mgr.
>   *
> - * Given a device node, get a reference to a fpga mgr.
> + * @node:	device node
>   *
>   * Return: fpga manager struct or IS_ERR() condition containing error code.
>   */
> @@ -478,7 +495,10 @@ EXPORT_SYMBOL_GPL(fpga_mgr_put);
>   * @mgr:	fpga manager
>   *
>   * Given a pointer to FPGA Manager (from fpga_mgr_get() or
> - * of_fpga_mgr_put()) attempt to get the mutex.
> + * of_fpga_mgr_put()) attempt to get the mutex. The user should call
> + * fpga_mgr_lock() and verify that it returns 0 before attempting to
> + * program the FPGA.  Likewise, the user should call fpga_mgr_unlock
> + * when done programming the FPGA.
>   *
>   * Return: 0 for success or -EBUSY
>   */
> @@ -494,7 +514,7 @@ int fpga_mgr_lock(struct fpga_manager *mgr)
>  EXPORT_SYMBOL_GPL(fpga_mgr_lock);
>  
>  /**
> - * fpga_mgr_unlock - Unlock FPGA manager
> + * fpga_mgr_unlock - Unlock FPGA manager after done programming
>   * @mgr:	fpga manager
>   */
>  void fpga_mgr_unlock(struct fpga_manager *mgr)
> -- 
> 2.7.4
> 

^ permalink raw reply	[flat|nested] 26+ messages in thread
* Re: [PATCH 06/14] fpga: mgr: kernel-doc fixes
  2018-05-16 23:49 ` [PATCH 06/14] fpga: mgr: kernel-doc fixes Alan Tull
  2018-05-23 17:14   ` Moritz Fischer
@ 2018-05-23 17:15   ` Moritz Fischer
  2018-05-24 17:07   ` Moritz Fischer
  2 siblings, 0 replies; 26+ messages in thread
From: Moritz Fischer @ 2018-05-23 17:15 UTC (permalink / raw)
  To: Alan Tull
  Cc: Greg Kroah-Hartman, Jonathan Corbet, Moritz Fischer,
	linux-kernel, linux-fpga

On Wed, May 16, 2018 at 06:49:59PM -0500, Alan Tull wrote:
> Clean up the kernel-doc documentation in fpga-mgr.c and fix the
> following warnings when documentation is built:
> 
> ./drivers/fpga/fpga-mgr.c:252: warning: Function parameter or member
> 'info' not described in 'fpga_mgr_buf_load'
> 
> ./drivers/fpga/fpga-mgr.c:252: warning: Excess function parameter
> 'flags' description in 'fpga_mgr_buf_load'
> 
> Signed-off-by: Alan Tull <atull@kernel.org>
Acked-by: Moritz Fischer <mdf@kernel.org>
> ---
>  drivers/fpga/fpga-mgr.c | 38 +++++++++++++++++++++++++++++---------
>  1 file changed, 29 insertions(+), 9 deletions(-)
> 
> diff --git a/drivers/fpga/fpga-mgr.c b/drivers/fpga/fpga-mgr.c
> index 151ac36..5fffeef 100644
> --- a/drivers/fpga/fpga-mgr.c
> +++ b/drivers/fpga/fpga-mgr.c
> @@ -21,6 +21,12 @@
>  static DEFINE_IDA(fpga_mgr_ida);
>  static struct class *fpga_mgr_class;
>  
> +/**
> + * fpga_image_info_alloc - Allocate a FPGA image info struct
> + * @dev: owning device
> + *
> + * Return: struct fpga_image_info or NULL
> + */
>  struct fpga_image_info *fpga_image_info_alloc(struct device *dev)
>  {
>  	struct fpga_image_info *info;
> @@ -39,6 +45,10 @@ struct fpga_image_info *fpga_image_info_alloc(struct device *dev)
>  }
>  EXPORT_SYMBOL_GPL(fpga_image_info_alloc);
>  
> +/**
> + * fpga_image_info_free - Free a FPGA image info struct
> + * @info: FPGA image info struct to free
> + */
>  void fpga_image_info_free(struct fpga_image_info *info)
>  {
>  	struct device *dev;
> @@ -223,7 +233,7 @@ static int fpga_mgr_buf_load_mapped(struct fpga_manager *mgr,
>  /**
>   * fpga_mgr_buf_load - load fpga from image in buffer
>   * @mgr:	fpga manager
> - * @flags:	flags setting fpga confuration modes
> + * @info:	fpga image info
>   * @buf:	buffer contain fpga image
>   * @count:	byte count of buf
>   *
> @@ -332,6 +342,16 @@ static int fpga_mgr_firmware_load(struct fpga_manager *mgr,
>  	return ret;
>  }
>  
> +/**
> + * fpga_mgr_load - load FPGA from scatter/gather table, buffer, or firmware
> + * @mgr:	fpga manager
> + * @info:	fpga image information.
> + *
> + * Load the FPGA from an image which is indicated in @info.  If successful, the
> + * FPGA ends up in operating mode.
> + *
> + * Return: 0 on success, negative error code otherwise.
> + */
>  int fpga_mgr_load(struct fpga_manager *mgr, struct fpga_image_info *info)
>  {
>  	if (info->sgt)
> @@ -418,11 +438,9 @@ static int fpga_mgr_dev_match(struct device *dev, const void *data)
>  }
>  
>  /**
> - * fpga_mgr_get - get a reference to a fpga mgr
> + * fpga_mgr_get - Given a device, get a reference to a fpga mgr.
>   * @dev:	parent device that fpga mgr was registered with
>   *
> - * Given a device, get a reference to a fpga mgr.
> - *
>   * Return: fpga manager struct or IS_ERR() condition containing error code.
>   */
>  struct fpga_manager *fpga_mgr_get(struct device *dev)
> @@ -442,10 +460,9 @@ static int fpga_mgr_of_node_match(struct device *dev, const void *data)
>  }
>  
>  /**
> - * of_fpga_mgr_get - get a reference to a fpga mgr
> - * @node:	device node
> + * of_fpga_mgr_get - Given a device node, get a reference to a fpga mgr.
>   *
> - * Given a device node, get a reference to a fpga mgr.
> + * @node:	device node
>   *
>   * Return: fpga manager struct or IS_ERR() condition containing error code.
>   */
> @@ -478,7 +495,10 @@ EXPORT_SYMBOL_GPL(fpga_mgr_put);
>   * @mgr:	fpga manager
>   *
>   * Given a pointer to FPGA Manager (from fpga_mgr_get() or
> - * of_fpga_mgr_put()) attempt to get the mutex.
> + * of_fpga_mgr_put()) attempt to get the mutex. The user should call
> + * fpga_mgr_lock() and verify that it returns 0 before attempting to
> + * program the FPGA.  Likewise, the user should call fpga_mgr_unlock
> + * when done programming the FPGA.
>   *
>   * Return: 0 for success or -EBUSY
>   */
> @@ -494,7 +514,7 @@ int fpga_mgr_lock(struct fpga_manager *mgr)
>  EXPORT_SYMBOL_GPL(fpga_mgr_lock);
>  
>  /**
> - * fpga_mgr_unlock - Unlock FPGA manager
> + * fpga_mgr_unlock - Unlock FPGA manager after done programming
>   * @mgr:	fpga manager
>   */
>  void fpga_mgr_unlock(struct fpga_manager *mgr)
> -- 
> 2.7.4
> 

^ permalink raw reply	[flat|nested] 26+ messages in thread
* Re: [PATCH 06/14] fpga: mgr: kernel-doc fixes
  2018-05-16 23:49 ` [PATCH 06/14] fpga: mgr: kernel-doc fixes Alan Tull
  2018-05-23 17:14   ` Moritz Fischer
  2018-05-23 17:15   ` Moritz Fischer
@ 2018-05-24 17:07   ` Moritz Fischer
  2 siblings, 0 replies; 26+ messages in thread
From: Moritz Fischer @ 2018-05-24 17:07 UTC (permalink / raw)
  To: Alan Tull
  Cc: Greg Kroah-Hartman, Jonathan Corbet, Moritz Fischer,
	linux-kernel, linux-fpga

On Wed, May 16, 2018 at 06:49:59PM -0500, Alan Tull wrote:
> Clean up the kernel-doc documentation in fpga-mgr.c and fix the
> following warnings when documentation is built:
> 
> ./drivers/fpga/fpga-mgr.c:252: warning: Function parameter or member
> 'info' not described in 'fpga_mgr_buf_load'
> 
> ./drivers/fpga/fpga-mgr.c:252: warning: Excess function parameter
> 'flags' description in 'fpga_mgr_buf_load'
> 
> Signed-off-by: Alan Tull <atull@kernel.org>
Acked-by: Moritz Fischer <mdf@kernel.org>
> ---
>  drivers/fpga/fpga-mgr.c | 38 +++++++++++++++++++++++++++++---------
>  1 file changed, 29 insertions(+), 9 deletions(-)
> 
> diff --git a/drivers/fpga/fpga-mgr.c b/drivers/fpga/fpga-mgr.c
> index 151ac36..5fffeef 100644
> --- a/drivers/fpga/fpga-mgr.c
> +++ b/drivers/fpga/fpga-mgr.c
> @@ -21,6 +21,12 @@
>  static DEFINE_IDA(fpga_mgr_ida);
>  static struct class *fpga_mgr_class;
>  
> +/**
> + * fpga_image_info_alloc - Allocate a FPGA image info struct
> + * @dev: owning device
> + *
> + * Return: struct fpga_image_info or NULL
> + */
>  struct fpga_image_info *fpga_image_info_alloc(struct device *dev)
>  {
>  	struct fpga_image_info *info;
> @@ -39,6 +45,10 @@ struct fpga_image_info *fpga_image_info_alloc(struct device *dev)
>  }
>  EXPORT_SYMBOL_GPL(fpga_image_info_alloc);
>  
> +/**
> + * fpga_image_info_free - Free a FPGA image info struct
> + * @info: FPGA image info struct to free
> + */
>  void fpga_image_info_free(struct fpga_image_info *info)
>  {
>  	struct device *dev;
> @@ -223,7 +233,7 @@ static int fpga_mgr_buf_load_mapped(struct fpga_manager *mgr,
>  /**
>   * fpga_mgr_buf_load - load fpga from image in buffer
>   * @mgr:	fpga manager
> - * @flags:	flags setting fpga confuration modes
> + * @info:	fpga image info
>   * @buf:	buffer contain fpga image
>   * @count:	byte count of buf
>   *
> @@ -332,6 +342,16 @@ static int fpga_mgr_firmware_load(struct fpga_manager *mgr,
>  	return ret;
>  }
>  
> +/**
> + * fpga_mgr_load - load FPGA from scatter/gather table, buffer, or firmware
> + * @mgr:	fpga manager
> + * @info:	fpga image information.
> + *
> + * Load the FPGA from an image which is indicated in @info.  If successful, the
> + * FPGA ends up in operating mode.
> + *
> + * Return: 0 on success, negative error code otherwise.
> + */
>  int fpga_mgr_load(struct fpga_manager *mgr, struct fpga_image_info *info)
>  {
>  	if (info->sgt)
> @@ -418,11 +438,9 @@ static int fpga_mgr_dev_match(struct device *dev, const void *data)
>  }
>  
>  /**
> - * fpga_mgr_get - get a reference to a fpga mgr
> + * fpga_mgr_get - Given a device, get a reference to a fpga mgr.
>   * @dev:	parent device that fpga mgr was registered with
>   *
> - * Given a device, get a reference to a fpga mgr.
> - *
>   * Return: fpga manager struct or IS_ERR() condition containing error code.
>   */
>  struct fpga_manager *fpga_mgr_get(struct device *dev)
> @@ -442,10 +460,9 @@ static int fpga_mgr_of_node_match(struct device *dev, const void *data)
>  }
>  
>  /**
> - * of_fpga_mgr_get - get a reference to a fpga mgr
> - * @node:	device node
> + * of_fpga_mgr_get - Given a device node, get a reference to a fpga mgr.
>   *
> - * Given a device node, get a reference to a fpga mgr.
> + * @node:	device node
>   *
>   * Return: fpga manager struct or IS_ERR() condition containing error code.
>   */
> @@ -478,7 +495,10 @@ EXPORT_SYMBOL_GPL(fpga_mgr_put);
>   * @mgr:	fpga manager
>   *
>   * Given a pointer to FPGA Manager (from fpga_mgr_get() or
> - * of_fpga_mgr_put()) attempt to get the mutex.
> + * of_fpga_mgr_put()) attempt to get the mutex. The user should call
> + * fpga_mgr_lock() and verify that it returns 0 before attempting to
> + * program the FPGA.  Likewise, the user should call fpga_mgr_unlock
> + * when done programming the FPGA.
>   *
>   * Return: 0 for success or -EBUSY
>   */
> @@ -494,7 +514,7 @@ int fpga_mgr_lock(struct fpga_manager *mgr)
>  EXPORT_SYMBOL_GPL(fpga_mgr_lock);
>  
>  /**
> - * fpga_mgr_unlock - Unlock FPGA manager
> + * fpga_mgr_unlock - Unlock FPGA manager after done programming
>   * @mgr:	fpga manager
>   */
>  void fpga_mgr_unlock(struct fpga_manager *mgr)
> -- 
> 2.7.4
> 

^ permalink raw reply	[flat|nested] 26+ messages in thread
* Re: [PATCH 07/14] fpga: bridge: kernel-doc fixes
  2018-05-16 23:50 ` [PATCH 07/14] fpga: bridge: " Alan Tull
@ 2018-05-24 17:08   ` Moritz Fischer
  0 siblings, 0 replies; 26+ messages in thread
From: Moritz Fischer @ 2018-05-24 17:08 UTC (permalink / raw)
  To: Alan Tull
  Cc: Greg Kroah-Hartman, Jonathan Corbet, Moritz Fischer,
	linux-kernel, linux-fpga

On Wed, May 16, 2018 at 06:50:00PM -0500, Alan Tull wrote:
> Fix the following warnings when documentation is built:
> 
> ./drivers/fpga/fpga-bridge.c:143: warning: Function parameter or
> member 'info' not described in 'fpga_bridge_get'
> 
> ./drivers/fpga/fpga-bridge.c:1: warning: no structured comments found
> 
> Signed-off-by: Alan Tull <atull@kernel.org>
Acked-by: Moritz Fischer <mdf@kernel.org>
> ---
>  drivers/fpga/fpga-bridge.c | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/drivers/fpga/fpga-bridge.c b/drivers/fpga/fpga-bridge.c
> index 164eb55..4b207a7 100644
> --- a/drivers/fpga/fpga-bridge.c
> +++ b/drivers/fpga/fpga-bridge.c
> @@ -121,6 +121,7 @@ static int fpga_bridge_dev_match(struct device *dev, const void *data)
>  /**
>   * fpga_bridge_get - get an exclusive reference to a fpga bridge
>   * @dev:	parent device that fpga bridge was registered with
> + * @info:	fpga manager info
>   *
>   * Given a device, get an exclusive reference to a fpga bridge.
>   *
> -- 
> 2.7.4
> 

^ permalink raw reply	[flat|nested] 26+ messages in thread
* Re: [PATCH 08/14] fpga: region: kernel-doc fixes
  2018-05-16 23:50 ` [PATCH 08/14] fpga: region: " Alan Tull
@ 2018-05-24 17:09   ` Moritz Fischer
  0 siblings, 0 replies; 26+ messages in thread
From: Moritz Fischer @ 2018-05-24 17:09 UTC (permalink / raw)
  To: Alan Tull
  Cc: Greg Kroah-Hartman, Jonathan Corbet, Moritz Fischer,
	linux-kernel, linux-fpga

On Wed, May 16, 2018 at 06:50:01PM -0500, Alan Tull wrote:
> Fix formatting and some cleanup for the kernel-doc documentation in
> fpga-region.c
> 
> Signed-off-by: Alan Tull <atull@kernel.org>
Acked-by: Moritz Fischer <mdf@kernel.org>
> ---
>  drivers/fpga/fpga-region.c | 7 +++++--
>  1 file changed, 5 insertions(+), 2 deletions(-)
> 
> diff --git a/drivers/fpga/fpga-region.c b/drivers/fpga/fpga-region.c
> index 0878f62..112fa3a 100644
> --- a/drivers/fpga/fpga-region.c
> +++ b/drivers/fpga/fpga-region.c
> @@ -81,13 +81,16 @@ static void fpga_region_put(struct fpga_region *region)
>  
>  /**
>   * fpga_region_program_fpga - program FPGA
> + *
>   * @region: FPGA region
> + *
>   * Program an FPGA using fpga image info (region->info).
>   * If the region has a get_bridges function, the exclusive reference for the
>   * bridges will be held if programming succeeds.  This is intended to prevent
>   * reprogramming the region until the caller considers it safe to do so.
>   * The caller will need to call fpga_bridges_put() before attempting to
>   * reprogram the region.
> + *
>   * Return 0 for success or negative error code.
>   */
>  int fpga_region_program_fpga(struct fpga_region *region)
> @@ -216,7 +219,7 @@ void fpga_region_free(struct fpga_region *region)
>  }
>  EXPORT_SYMBOL_GPL(fpga_region_free);
>  
> -/*
> +/**
>   * fpga_region_register - register a FPGA region
>   * @region: FPGA region created by fpga_region_create
>   * Return: 0 or -errno
> @@ -228,7 +231,7 @@ int fpga_region_register(struct fpga_region *region)
>  }
>  EXPORT_SYMBOL_GPL(fpga_region_register);
>  
> -/*
> +/**
>   * fpga_region_unregister - unregister a FPGA region
>   * @region: FPGA region
>   */
> -- 
> 2.7.4
> 

Thanks,
Moritz

^ permalink raw reply	[flat|nested] 26+ messages in thread
* Re: [PATCH 09/14] Documentation: fpga: move fpga overview to driver-api
  2018-05-16 23:50 ` [PATCH 09/14] Documentation: fpga: move fpga overview to driver-api Alan Tull
@ 2018-05-26  2:21   ` Randy Dunlap
  0 siblings, 0 replies; 26+ messages in thread
From: Randy Dunlap @ 2018-05-26  2:21 UTC (permalink / raw)
  To: Alan Tull, Greg Kroah-Hartman, Jonathan Corbet, Moritz Fischer
  Cc: linux-kernel, linux-fpga

On 05/16/2018 04:50 PM, Alan Tull wrote:
> Start of moving Documentation/fpga/*.txt to driver-api, including:
>  - Add new directory driver-api/fpga
>  - Add new file driver-api/fpga/index.rst
>  - Add driver-api/fpga to driver-api/index.rst
>  - Move Documentation/fpga/overview.txt to driver-api/fpga/intro.rst
>  - Formatting and rewrites so that intro.rst will build cleanly
>    and form a good introduction to the rest of the docs to be added.
> 
> Signed-off-by: Alan Tull <atull@kernel.org>
> ---
>  Documentation/driver-api/fpga/index.rst | 10 ++++++
>  Documentation/driver-api/fpga/intro.rst | 54 +++++++++++++++++++++++++++++++++
>  Documentation/driver-api/index.rst      |  1 +
>  Documentation/fpga/overview.txt         | 23 --------------
>  4 files changed, 65 insertions(+), 23 deletions(-)
>  create mode 100644 Documentation/driver-api/fpga/index.rst
>  create mode 100644 Documentation/driver-api/fpga/intro.rst
>  delete mode 100644 Documentation/fpga/overview.txt

Hi,
Just a few comments for you.

> diff --git a/Documentation/driver-api/fpga/intro.rst b/Documentation/driver-api/fpga/intro.rst
> new file mode 100644
> index 0000000..51cd81d
> --- /dev/null
> +++ b/Documentation/driver-api/fpga/intro.rst
> @@ -0,0 +1,54 @@
> +Introduction
> +============
> +
> +The FPGA subsystem supports reprogramming FPGAs dynamically under
> +Linux.  Some of the core intentions of the FPGA subsystems are:
> +
> +* The FPGA subsystem is vendor agnostic.
> +
> +* The FPGA subsystem separates upper layers (userspace interfaces and
> +  enumeration) from lower layers that know how to program a specific
> +  FPGA.
> +
> +* Code should not be shared between upper and lower layers.  This
> +  should go without saying.  If that seems necessary, there's probably
> +  framework functionality that that can be added that will benefit

                             that      can be

> +  other users.  Write the linux-fpga mailing list and maintainers and
> +  seek out a solution that expands the framework for broad reuse.

                          choose one spelling:                ^^^^vvvvv

> +* Generally, when adding code, think of the future.  Plan for re-use.
> +
> +The framework in the kernel is divided into:
> +
> +FPGA Manager
> +------------
> +
> +If you are adding a new FPGA or a new method of programming a FPGA,
> +this is the subsystem for you.  Low level FPGA manager drivers contain
> +the knowledge of how to program a specific device.  This subsystem
> +includes the framework in fpga-mgr.c and the low level drivers that
> +are registered with it.
> +
> +FPGA Bridge
> +-----------
> +
> +FPGA Bridges prevent spurious signals from going out of a FPGA or a

                                                        of an

> +region of a FPGA during programming.  They are disabled before

          of an 

> +programming begins and re-enabled afterwards.  An FPGA bridge may be
> +actual hard hardware that gates a bus to a cpu or a soft ("freeze")

                                              CPU

> +bridge in FPGA fabric that surrounds a partial reconfiguration region
> +of an FPGA.  This subsystem includes fpga-bridge.c and the low level
> +drivers that are registered with it.
> +
> +FPGA Region
> +-----------
> +
> +If you are adding a new interface to the FPGA framework, add it on top
> +of a FPGA region to allow the most reuse of your interface.

   of an

> +
> +The FPGA Region framework (fpga-region.c) associates managers and
> +bridges as reconfigurable regions.  A region may refer to the whole
> +FPGA in full reconfiguration or to a partial reconfiguration region.
> +
> +The Device Tree FPGA Region support (of-fpga-region.c) handles
> +reprogramming FPGAs when device tree overlays are applied.



-- 
~Randy

^ permalink raw reply	[flat|nested] 26+ messages in thread
* Re: [PATCH 10/14] documentation: fpga: move fpga-mgr.txt to driver-api
  2018-05-16 23:50 ` [PATCH 10/14] documentation: fpga: move fpga-mgr.txt " Alan Tull
@ 2018-05-26  2:29   ` Randy Dunlap
  0 siblings, 0 replies; 26+ messages in thread
From: Randy Dunlap @ 2018-05-26  2:29 UTC (permalink / raw)
  To: Alan Tull, Greg Kroah-Hartman, Jonathan Corbet, Moritz Fischer
  Cc: linux-kernel, linux-fpga

On 05/16/2018 04:50 PM, Alan Tull wrote:
> Move Documentation/fpga/fpga-mgr.txt to driver-api/fpga/fpga-mgr.rst
> and:
>  - Add to driver-api/fpga/index.rst
>  - Format changes so documentation builds cleanly.
>  - Minor rewrites that make the doc flow better as ReST documentation.
>    - Such as moving API reference to end of doc
>  - Change API reference section to refer to kernel-doc documentation in
>    fpga-mgr.c driver code rather than statically defining each function.
> 
> Signed-off-by: Alan Tull <atull@kernel.org>
> ---
>  Documentation/driver-api/fpga/fpga-mgr.rst | 220 +++++++++++++++++++++++++++++
>  Documentation/driver-api/fpga/index.rst    |   1 +
>  Documentation/fpga/fpga-mgr.txt            | 218 ----------------------------
>  3 files changed, 221 insertions(+), 218 deletions(-)
>  create mode 100644 Documentation/driver-api/fpga/fpga-mgr.rst
>  delete mode 100644 Documentation/fpga/fpga-mgr.txt
> 
> diff --git a/Documentation/driver-api/fpga/fpga-mgr.rst b/Documentation/driver-api/fpga/fpga-mgr.rst
> new file mode 100644
> index 0000000..bcf2dd2
> --- /dev/null
> +++ b/Documentation/driver-api/fpga/fpga-mgr.rst
> @@ -0,0 +1,220 @@
> +FPGA Manager
> +============
> +
> +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.
> +
> +The FPGA image to be programmed can be in a scatter gather list, a single
> +contiguous buffer, or a firmware file.  Because allocating contiguous kernel
> +memory for the buffer should be avoided, users are encouraged to use a scatter
> +gather list instead if possible.
> +
> +The particulars for programming the image are presented in a structure (struct
> +fpga_image_info).  This struct contains parameters such as pointers to the
> +FPGA image as well as image-specific particulars such as whether the image was
> +built for full or partial reconfiguration.
> +
> +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;
> +		struct fpga_manager *mgr;
> +		int ret;
> +
> +		priv = devm_kzalloc(dev, sizeof(*priv), GFP_KERNEL);
> +		if (!priv)
> +			return -ENOMEM;
> +
> +		/*
> +		 * do ioremaps, get interrupts, etc. and save
> +		 * them in priv
> +		 */
> +
> +		mgr = fpga_mgr_create(dev, "Altera SOCFPGA FPGA Manager",
> +				      &socfpga_fpga_ops, priv);
> +		if (!mgr)
> +			return -ENOMEM;
> +
> +		platform_set_drvdata(pdev, mgr);
> +
> +		ret = fpga_mgr_register(mgr);
> +		if (ret)
> +			fpga_mgr_free(mgr);
> +
> +		return ret;
> +	}
> +
> +	static int socfpga_fpga_remove(struct platform_device *pdev)
> +	{
> +		struct fpga_manager *mgr = platform_get_drvdata(pdev);
> +
> +		fpga_mgr_unregister(mgr);
> +
> +		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 or .write_sg (may be called once or multiple times)
> + 3. .write_complete
> +
> +The .write_init function will prepare the FPGA to receive the image data.  The
> +buffer passed into .write_init will be atmost .initial_header_size bytes long,

                                          at most                           long;

> +if the whole bitstream is not immediately available then the core code will
> +buffer up at least this much before starting.
> +
> +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. This interface
> +is suitable for drivers which use PIO.
> +
> +The .write_sg version behaves the same as .write except the input is a sg_table
> +scatter list. This interface is suitable for drivers which use DMA.
> +
> +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.
> +
> +How to write an image buffer to a supported FPGA
> +------------------------------------------------
> +
> +Some sample code::
> +
> +	#include <linux/fpga/fpga-mgr.h>
> +
> +	struct fpga_manager *mgr;
> +	struct fpga_image_info *info;
> +	int ret;
> +
> +	/*
> +	 * Get a reference to FPGA manager.  The manager is not locked, so you can
> +	 * hold onto this reference without it preventing programming.
> +	 *
> +	 * This example uses the device node of the manager.  Alternatively, use
> +	 * fpga_mgr_get(dev) instead if you have the device.
> +	 */
> +	mgr = of_fpga_mgr_get(mgr_node);
> +
> +	/* struct with information about the FPGA image to program. */
> +	info = fpga_image_info_alloc(dev);
> +
> +	/* flags indicates whether to do full or partial reconfiguration */
> +	info->flags = FPGA_MGR_PARTIAL_RECONFIG;
> +
> +	/*
> +	 * At this point, indicate where the image is. This is pseudo-code; you're
> +	 * going to use one of these three.
> +	 */
> +	if (image is in a scatter gather table) {
> +
> +		info->sgt = [your scatter gather table]
> +
> +	} else if (image is in a buffer) {
> +
> +		info->buf = [your image buffer]
> +		info->count = [image buffer size]
> +
> +	} else if (image is in a firmware file) {
> +
> +		info->firmware_name = devm_kstrdup(dev, firmware_name, GFP_KERNEL);
> +
> +	}
> +
> +	/* Get exclusive control of FPGA manager */
> +	ret = fpga_mgr_lock(mgr);
> +
> +	/* Load the buffer to the FPGA */
> +	ret = fpga_mgr_buf_load(mgr, &info, buf, count);
> +
> +	/* Release the FPGA manager */
> +	fpga_mgr_unlock(mgr);
> +	fpga_mgr_put(mgr);
> +
> +	/* Deallocate the image info if you're done with it */
> +	fpga_image_info_free(info);
> +
> +API for implementing a new FPGA Manager driver
> +----------------------------------------------
> +
> +.. kernel-doc:: include/linux/fpga/fpga-mgr.h
> +   :functions: fpga_manager
> +
> +.. kernel-doc:: include/linux/fpga/fpga-mgr.h
> +   :functions: fpga_manager_ops
> +
> +.. kernel-doc:: drivers/fpga/fpga-mgr.c
> +   :functions: fpga_mgr_create
> +
> +.. kernel-doc:: drivers/fpga/fpga-mgr.c
> +   :functions: fpga_mgr_free
> +
> +.. kernel-doc:: drivers/fpga/fpga-mgr.c
> +   :functions: fpga_mgr_register
> +
> +.. kernel-doc:: drivers/fpga/fpga-mgr.c
> +   :functions: fpga_mgr_unregister
> +
> +API for programming a FPGA
> +--------------------------
> +
> +.. kernel-doc:: include/linux/fpga/fpga-mgr.h
> +   :functions: fpga_image_info
> +
> +.. kernel-doc:: include/linux/fpga/fpga-mgr.h
> +   :functions: fpga_mgr_states
> +
> +.. kernel-doc:: drivers/fpga/fpga-mgr.c
> +   :functions: fpga_image_info_alloc
> +
> +.. kernel-doc:: drivers/fpga/fpga-mgr.c
> +   :functions: fpga_image_info_free
> +
> +.. kernel-doc:: drivers/fpga/fpga-mgr.c
> +   :functions: of_fpga_mgr_get
> +
> +.. kernel-doc:: drivers/fpga/fpga-mgr.c
> +   :functions: fpga_mgr_get
> +
> +.. kernel-doc:: drivers/fpga/fpga-mgr.c
> +   :functions: fpga_mgr_put
> +
> +.. kernel-doc:: drivers/fpga/fpga-mgr.c
> +   :functions: fpga_mgr_lock
> +
> +.. kernel-doc:: drivers/fpga/fpga-mgr.c
> +   :functions: fpga_mgr_unlock
> +
> +.. kernel-doc:: include/linux/fpga/fpga-mgr.h
> +   :functions: fpga_mgr_states
> +
> +Note - use :c:func:`fpga_region_program_fpga()` instead of :c:func:`fpga_mgr_load()`
> +
> +.. kernel-doc:: drivers/fpga/fpga-mgr.c
> +   :functions: fpga_mgr_load


-- 
~Randy

^ permalink raw reply	[flat|nested] 26+ messages in thread
* Re: [PATCH 12/14] documentation: fpga: move fpga-region.txt to driver-api
  2018-05-16 23:50 ` [PATCH 12/14] documentation: fpga: move fpga-region.txt " Alan Tull
@ 2018-05-26  2:33   ` Randy Dunlap
  2018-05-29 16:15     ` Alan Tull
  0 siblings, 1 reply; 26+ messages in thread
From: Randy Dunlap @ 2018-05-26  2:33 UTC (permalink / raw)
  To: Alan Tull, Greg Kroah-Hartman, Jonathan Corbet, Moritz Fischer
  Cc: linux-kernel, linux-fpga

On 05/16/2018 04:50 PM, Alan Tull wrote:
> Move Documentation/fpga/fpga-region.txt to
> driver-api/fpga/fpga-region.rst.  Including:
>  - Add it to driver-api/fpga/index.rst
>  - Formatting changes to build cleanly as ReST documentation
>  - Some rewrites for better flow as a ReST doc such as moving
>    API reference to the end of the doc
>  - Rewrite API reference section to refer to kernel-doc
>    documentation in fpga-region.c driver code
> 
> Signed-off-by: Alan Tull <atull@kernel.org>
> ---
>  Documentation/driver-api/fpga/fpga-region.rst | 102 ++++++++++++++++++++++++++
>  Documentation/driver-api/fpga/index.rst       |   1 +
>  Documentation/fpga/fpga-region.txt            |  94 ------------------------
>  3 files changed, 103 insertions(+), 94 deletions(-)
>  create mode 100644 Documentation/driver-api/fpga/fpga-region.rst
>  delete mode 100644 Documentation/fpga/fpga-region.txt
> 
> diff --git a/Documentation/driver-api/fpga/fpga-region.rst b/Documentation/driver-api/fpga/fpga-region.rst
> new file mode 100644
> index 0000000..f89e4a3
> --- /dev/null
> +++ b/Documentation/driver-api/fpga/fpga-region.rst
> @@ -0,0 +1,102 @@
> +FPGA Region
> +===========
> +
> +Overview
> +--------
> +
> +This document is meant to be an brief overview of the FPGA region API usage.  A

                                a brief overview

> +more conceptual look at regions can be found in the Device Tree binding
> +document [#f1]_.
> +
> +For the purposes of this API document, let's just say that a region associates
> +an FPGA Manager and a bridge (or bridges) with a reprogrammable region of an
> +FPGA or the whole FPGA.  The API provides a way to register a region and to
> +program a region.
> +
> +Currently the only layer above fpga-region.c in the kernel is the Device Tree
> +support (of-fpga-region.c) described in [#f1]_.  The DT support layer uses regions
> +to program the FPGA and then DT to handle enumeration.  The common region code
> +is intended to be used by other schemes that have other ways of accomplishing
> +enumeration after programming.
> +
> +An fpga-region can be set up to know the following things:
> +
> + * which FPGA manager to use to do the programming
> +
> + * which bridges to disable before programming and enable afterwards.
> +
> +Additional info needed to program the FPGA image is passed in the struct
> +fpga_image_info including:
> +
> + * pointers to the image as either a scatter-gather buffer, a contiguous
> +   buffer, or the name of firmware file
> +
> + * flags indicating specifics such as whether the image if for partial

                                                           is for

> +   reconfiguration.
> +
> +How to program a FPGA using a region

                  an FPGA

> +------------------------------------
> +
> +First, allocate the info struct::
> +
> +	info = fpga_image_info_alloc(dev);
> +	if (!info)
> +		return -ENOMEM;
> +
> +Set flags as needed, i.e.::
> +
> +	info->flags |= FPGA_MGR_PARTIAL_RECONFIG;
> +
> +Point to your FPGA image, such as::
> +
> +	info->sgt = &sgt;
> +
> +Add info to region and do the programming::
> +
> +	region->info = info;
> +	ret = fpga_region_program_fpga(region);
> +
> +:c:func:`fpga_region_program_fpga()` operates on info passed in the
> +fpga_image_info (region->info).  This function will attempt to:
> +
> + * lock the region's mutex
> + * lock the region's FPGA manager
> + * build a list of FPGA bridges if a method has been specified to do so
> + * disable the bridges
> + * program the FPGA
> + * re-enable the bridges
> + * release the locks
> +
> +Then you will want to enumerate whatever hardware has appeared in the FPGA.
> +
> +How to add a new FPGA region
> +----------------------------
> +
> +An example of usage can be seen in the probe function of [#f2]_.
> +
> +.. [#f1] ../devicetree/bindings/fpga/fpga-region.txt
> +.. [#f2] ../../drivers/fpga/of-fpga-region.c
> +
> +API to program a FGPA
> +---------------------
> +
> +.. kernel-doc:: drivers/fpga/fpga-region.c
> +   :functions: fpga_region_program_fpga
> +
> +API to add a new FPGA region
> +----------------------------
> +
> +.. kernel-doc:: include/linux/fpga/fpga-region.h
> +   :functions: fpga_region
> +
> +.. kernel-doc:: drivers/fpga/fpga-region.c
> +   :functions: fpga_region_create
> +
> +.. kernel-doc:: drivers/fpga/fpga-region.c
> +   :functions: fpga_region_free
> +
> +.. kernel-doc:: drivers/fpga/fpga-region.c
> +   :functions: fpga_region_register
> +
> +.. kernel-doc:: drivers/fpga/fpga-region.c
> +   :functions: fpga_region_unregister


-- 
~Randy

^ permalink raw reply	[flat|nested] 26+ messages in thread
* Re: [PATCH 12/14] documentation: fpga: move fpga-region.txt to driver-api
  2018-05-26  2:33   ` Randy Dunlap
@ 2018-05-29 16:15     ` Alan Tull
  0 siblings, 0 replies; 26+ messages in thread
From: Alan Tull @ 2018-05-29 16:15 UTC (permalink / raw)
  To: Randy Dunlap
  Cc: Greg Kroah-Hartman, Jonathan Corbet, Moritz Fischer,
	linux-kernel, linux-fpga

On Fri, May 25, 2018 at 9:33 PM, Randy Dunlap <rdunlap@infradead.org> wrote:

Hi Randy,

Thanks for the reviews.  These are up on char-misc-next already, so
I'll send a patch to fix.

Alan

> On 05/16/2018 04:50 PM, Alan Tull wrote:
>> Move Documentation/fpga/fpga-region.txt to
>> driver-api/fpga/fpga-region.rst.  Including:
>>  - Add it to driver-api/fpga/index.rst
>>  - Formatting changes to build cleanly as ReST documentation
>>  - Some rewrites for better flow as a ReST doc such as moving
>>    API reference to the end of the doc
>>  - Rewrite API reference section to refer to kernel-doc
>>    documentation in fpga-region.c driver code
>>
>> Signed-off-by: Alan Tull <atull@kernel.org>
>> ---
>>  Documentation/driver-api/fpga/fpga-region.rst | 102 ++++++++++++++++++++++++++
>>  Documentation/driver-api/fpga/index.rst       |   1 +
>>  Documentation/fpga/fpga-region.txt            |  94 ------------------------
>>  3 files changed, 103 insertions(+), 94 deletions(-)
>>  create mode 100644 Documentation/driver-api/fpga/fpga-region.rst
>>  delete mode 100644 Documentation/fpga/fpga-region.txt
>>
>> diff --git a/Documentation/driver-api/fpga/fpga-region.rst b/Documentation/driver-api/fpga/fpga-region.rst
>> new file mode 100644
>> index 0000000..f89e4a3
>> --- /dev/null
>> +++ b/Documentation/driver-api/fpga/fpga-region.rst
>> @@ -0,0 +1,102 @@
>> +FPGA Region
>> +===========
>> +
>> +Overview
>> +--------
>> +
>> +This document is meant to be an brief overview of the FPGA region API usage.  A
>
>                                 a brief overview
>
>> +more conceptual look at regions can be found in the Device Tree binding
>> +document [#f1]_.
>> +
>> +For the purposes of this API document, let's just say that a region associates
>> +an FPGA Manager and a bridge (or bridges) with a reprogrammable region of an
>> +FPGA or the whole FPGA.  The API provides a way to register a region and to
>> +program a region.
>> +
>> +Currently the only layer above fpga-region.c in the kernel is the Device Tree
>> +support (of-fpga-region.c) described in [#f1]_.  The DT support layer uses regions
>> +to program the FPGA and then DT to handle enumeration.  The common region code
>> +is intended to be used by other schemes that have other ways of accomplishing
>> +enumeration after programming.
>> +
>> +An fpga-region can be set up to know the following things:
>> +
>> + * which FPGA manager to use to do the programming
>> +
>> + * which bridges to disable before programming and enable afterwards.
>> +
>> +Additional info needed to program the FPGA image is passed in the struct
>> +fpga_image_info including:
>> +
>> + * pointers to the image as either a scatter-gather buffer, a contiguous
>> +   buffer, or the name of firmware file
>> +
>> + * flags indicating specifics such as whether the image if for partial
>
>                                                            is for
>
>> +   reconfiguration.
>> +
>> +How to program a FPGA using a region
>
>                   an FPGA
>
>> +------------------------------------
>> +
>> +First, allocate the info struct::
>> +
>> +     info = fpga_image_info_alloc(dev);
>> +     if (!info)
>> +             return -ENOMEM;
>> +
>> +Set flags as needed, i.e.::
>> +
>> +     info->flags |= FPGA_MGR_PARTIAL_RECONFIG;
>> +
>> +Point to your FPGA image, such as::
>> +
>> +     info->sgt = &sgt;
>> +
>> +Add info to region and do the programming::
>> +
>> +     region->info = info;
>> +     ret = fpga_region_program_fpga(region);
>> +
>> +:c:func:`fpga_region_program_fpga()` operates on info passed in the
>> +fpga_image_info (region->info).  This function will attempt to:
>> +
>> + * lock the region's mutex
>> + * lock the region's FPGA manager
>> + * build a list of FPGA bridges if a method has been specified to do so
>> + * disable the bridges
>> + * program the FPGA
>> + * re-enable the bridges
>> + * release the locks
>> +
>> +Then you will want to enumerate whatever hardware has appeared in the FPGA.
>> +
>> +How to add a new FPGA region
>> +----------------------------
>> +
>> +An example of usage can be seen in the probe function of [#f2]_.
>> +
>> +.. [#f1] ../devicetree/bindings/fpga/fpga-region.txt
>> +.. [#f2] ../../drivers/fpga/of-fpga-region.c
>> +
>> +API to program a FGPA
>> +---------------------
>> +
>> +.. kernel-doc:: drivers/fpga/fpga-region.c
>> +   :functions: fpga_region_program_fpga
>> +
>> +API to add a new FPGA region
>> +----------------------------
>> +
>> +.. kernel-doc:: include/linux/fpga/fpga-region.h
>> +   :functions: fpga_region
>> +
>> +.. kernel-doc:: drivers/fpga/fpga-region.c
>> +   :functions: fpga_region_create
>> +
>> +.. kernel-doc:: drivers/fpga/fpga-region.c
>> +   :functions: fpga_region_free
>> +
>> +.. kernel-doc:: drivers/fpga/fpga-region.c
>> +   :functions: fpga_region_register
>> +
>> +.. kernel-doc:: drivers/fpga/fpga-region.c
>> +   :functions: fpga_region_unregister
>
>
> --
> ~Randy

^ permalink raw reply	[flat|nested] 26+ messages in thread
end of thread, other threads:[~2018-05-29 16:16 UTC | newest]

Thread overview: 26+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2018-05-16 23:49 [PATCH 00/14] fpga api changes and kernel-doc fixup Alan Tull
2018-05-16 23:49 ` [PATCH 01/14] fpga: region: don't use drvdata in common fpga code Alan Tull
2018-05-16 23:49 ` [PATCH 02/14] fpga: manager: change api, don't use drvdata Alan Tull
2018-05-16 23:49 ` [PATCH 03/14] fpga: bridge: " Alan Tull
2018-05-16 23:49 ` [PATCH 04/14] fpga: region: change api, add fpga_region_create/free Alan Tull
2018-05-16 23:49 ` [PATCH 05/14] fpga: use SPDX Alan Tull
2018-05-16 23:49 ` [PATCH 06/14] fpga: mgr: kernel-doc fixes Alan Tull
2018-05-23 17:14   ` Moritz Fischer
2018-05-23 17:15   ` Moritz Fischer
2018-05-24 17:07   ` Moritz Fischer
2018-05-16 23:50 ` [PATCH 07/14] fpga: bridge: " Alan Tull
2018-05-24 17:08   ` Moritz Fischer
2018-05-16 23:50 ` [PATCH 08/14] fpga: region: " Alan Tull
2018-05-24 17:09   ` Moritz Fischer
2018-05-16 23:50 ` [PATCH 09/14] Documentation: fpga: move fpga overview to driver-api Alan Tull
2018-05-26  2:21   ` Randy Dunlap
2018-05-16 23:50 ` [PATCH 10/14] documentation: fpga: move fpga-mgr.txt " Alan Tull
2018-05-26  2:29   ` Randy Dunlap
2018-05-16 23:50 ` [PATCH 11/14] documentation: fpga: add bridge document " Alan Tull
2018-05-16 23:50 ` [PATCH 12/14] documentation: fpga: move fpga-region.txt " Alan Tull
2018-05-26  2:33   ` Randy Dunlap
2018-05-29 16:15     ` Alan Tull
2018-05-16 23:50 ` [PATCH 13/14] fpga: clarify that unregister functions also free Alan Tull
2018-05-16 23:50 ` [PATCH 14/14] MAINTAINERS: Add driver-api/fpga path Alan Tull
2018-05-17  7:04 ` [PATCH 00/14] fpga api changes and kernel-doc fixup Greg Kroah-Hartman
2018-05-17 14:08   ` Alan Tull

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.