Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 547b822c authored by Alan Tull's avatar Alan Tull Committed by Greg Kroah-Hartman
Browse files

documentation: fpga: move fpga-mgr.txt to driver-api 



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: default avatarAlan Tull <atull@kernel.org>
Signed-off-by: default avatarGreg Kroah-Hartman <gregkh@linuxfoundation.org>
parent 66c472cd

Documentation/fpga/fpga-mgr.txt→Documentation/driver-api/fpga/fpga-mgr.rst

+220 −0
Original line number Diff line number Diff line 
FPGA Manager Core



Alan Tull 2015

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
@@ -21,70 +20,93 @@ 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:

==============

How to support a new FPGA device

--------------------------------



To program the FPGA:

--------------------

To add another FPGA manager, write a driver that implements a set of ops.  The

probe function calls fpga_mgr_register(), such as::



	int fpga_mgr_load(struct fpga_manager *mgr,

			  struct fpga_image_info *info);

	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,

	};



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.

	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;



To allocate or free a struct fpga_image_info:

---------------------------------------------

		priv = devm_kzalloc(dev, sizeof(*priv), GFP_KERNEL);

		if (!priv)

			return -ENOMEM;



	struct fpga_image_info *fpga_image_info_alloc(struct device *dev);

		/*

		 * do ioremaps, get interrupts, etc. and save

		 * them in priv

		 */



	void fpga_image_info_free(struct fpga_image_info *info);

		mgr = fpga_mgr_create(dev, "Altera SOCFPGA FPGA Manager",

				      &socfpga_fpga_ops, priv);

		if (!mgr)

			return -ENOMEM;



To get/put a reference to a FPGA manager:

-----------------------------------------

		platform_set_drvdata(pdev, mgr);



	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);

		ret = fpga_mgr_register(mgr);

		if (ret)

			fpga_mgr_free(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.

		return ret;

	}



	static int socfpga_fpga_remove(struct platform_device *pdev)

	{

		struct fpga_manager *mgr = platform_get_drvdata(pdev);



To get exclusive control of a FPGA manager:

-------------------------------------------

		fpga_mgr_unregister(mgr);



	int fpga_mgr_lock(struct fpga_manager *mgr);

	void fpga_mgr_unlock(struct fpga_manager *mgr);

		return 0;

	}



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:

------------------------------------

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.



	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);

The programming sequence is::

 1. .write_init

 2. .write or .write_sg (may be called once or multiple times)

 3. .write_complete



To register or unregister the low level FPGA-specific driver:

-------------------------------------------------------------

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.



	int fpga_mgr_register(struct fpga_manager *mgr);

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.



	void fpga_mgr_unregister(struct fpga_manager *mgr);

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.



Use of these functions is described below in "How To Support a new FPGA

device."

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;
@@ -138,81 +160,61 @@ 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:

API for implementing a new FPGA Manager driver

----------------------------------------------



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,

};

.. kernel-doc:: include/linux/fpga/fpga-mgr.h

   :functions: fpga_manager



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;

.. kernel-doc:: include/linux/fpga/fpga-mgr.h

   :functions: fpga_manager_ops



	priv = devm_kzalloc(dev, sizeof(*priv), GFP_KERNEL);

	if (!priv)

		return -ENOMEM;

.. kernel-doc:: drivers/fpga/fpga-mgr.c

   :functions: fpga_mgr_create



	/* ... do ioremaps, get interrupts, etc. and save

	   them in priv... */

.. kernel-doc:: drivers/fpga/fpga-mgr.c

   :functions: fpga_mgr_free



	mgr = fpga_mgr_create(dev, "Altera SOCFPGA FPGA Manager",

			      &socfpga_fpga_ops, priv);

	if (!mgr)

		return -ENOMEM;

.. kernel-doc:: drivers/fpga/fpga-mgr.c

   :functions: fpga_mgr_register



	platform_set_drvdata(pdev, mgr);

.. kernel-doc:: drivers/fpga/fpga-mgr.c

   :functions: fpga_mgr_unregister



	ret = fpga_mgr_register(mgr);

	if (ret)

		fpga_mgr_free(mgr);

API for programming a FPGA

--------------------------



	return ret;

}

.. kernel-doc:: include/linux/fpga/fpga-mgr.h

   :functions: fpga_image_info



static int socfpga_fpga_remove(struct platform_device *pdev)

{

	struct fpga_manager *mgr = platform_get_drvdata(pdev);

.. kernel-doc:: include/linux/fpga/fpga-mgr.h

   :functions: fpga_mgr_states



	fpga_mgr_unregister(mgr);

.. kernel-doc:: drivers/fpga/fpga-mgr.c

   :functions: fpga_image_info_alloc



	return 0;

}

.. kernel-doc:: drivers/fpga/fpga-mgr.c

   :functions: fpga_image_info_free



.. kernel-doc:: drivers/fpga/fpga-mgr.c

   :functions: of_fpga_mgr_get



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.

.. kernel-doc:: drivers/fpga/fpga-mgr.c

   :functions: fpga_mgr_get



The programming sequence is:

 1. .write_init

 2. .write or .write_sg (may be called once or multiple times)

 3. .write_complete

.. kernel-doc:: drivers/fpga/fpga-mgr.c

   :functions: fpga_mgr_put



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.

.. kernel-doc:: drivers/fpga/fpga-mgr.c

   :functions: fpga_mgr_lock



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.

.. kernel-doc:: drivers/fpga/fpga-mgr.c

   :functions: fpga_mgr_unlock



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.

.. kernel-doc:: include/linux/fpga/fpga-mgr.h

   :functions: fpga_mgr_states



The .write_complete function is called after all the image has been written

to put the FPGA into operating mode.

Note - use :c:func:`fpga_region_program_fpga()` instead of :c:func:`fpga_mgr_load()`



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.
 
.. kernel-doc:: drivers/fpga/fpga-mgr.c

   :functions: fpga_mgr_load

Documentation/driver-api/fpga/index.rst

+1 −0
Original line number Diff line number Diff line
@@ -8,3 +8,4 @@ FPGA Subsystem 
   :maxdepth: 2



   intro

   fpga-mgr