[linux-block.git] / Documentation / fpga / fpga-region.txt

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
Commit	Line	Data
5cf0c7f6 AT	1	FPGA Regions
	2
	3	Alan Tull 2017
	4
	5	CONTENTS
	6	- Introduction
	7	- The FPGA region API
	8	- Usage example
	9
	10	Introduction
	11	============
	12
	13	This document is meant to be an brief overview of the FPGA region API usage. A
	14	more conceptual look at regions can be found in [1].
	15
	16	For the purposes of this API document, let's just say that a region associates
	17	an FPGA Manager and a bridge (or bridges) with a reprogrammable region of an
	18	FPGA or the whole FPGA. The API provides a way to register a region and to
	19	program a region.
	20
	21	Currently the only layer above fpga-region.c in the kernel is the Device Tree
	22	support (of-fpga-region.c) described in [1]. The DT support layer uses regions
	23	to program the FPGA and then DT to handle enumeration. The common region code
	24	is intended to be used by other schemes that have other ways of accomplishing
	25	enumeration after programming.
	26
	27	An fpga-region can be set up to know the following things:
	28	* which FPGA manager to use to do the programming
	29	* which bridges to disable before programming and enable afterwards.
	30
	31	Additional info needed to program the FPGA image is passed in the struct
	32	fpga_image_info [2] including:
	33	* pointers to the image as either a scatter-gather buffer, a contiguous
	34	buffer, or the name of firmware file
	35	* flags indicating specifics such as whether the image if for partial
	36	reconfiguration.
	37
	38	===================
	39	The FPGA region API
	40	===================
	41
	42	To register or unregister a region:
	43	-----------------------------------
	44
9f368977	45	int fpga_region_register(struct fpga_region *region);
5cf0c7f6 AT	46	int fpga_region_unregister(struct fpga_region *region);
	47
	48	An example of usage can be seen in the probe function of [3]
	49
	50	To program an FPGA:
	51	-------------------
	52	int fpga_region_program_fpga(struct fpga_region *region);
	53
	54	This function operates on info passed in the fpga_image_info
	55	(region->info).
	56
	57	This function will attempt to:
	58	* lock the region's mutex
	59	* lock the region's FPGA manager
	60	* build a list of FPGA bridges if a method has been specified to do so
	61	* disable the bridges
	62	* program the FPGA
	63	* re-enable the bridges
	64	* release the locks
	65
	66	=============
	67	Usage example
	68	=============
	69
	70	First, allocate the info struct:
	71
	72	info = fpga_image_info_alloc(dev);
	73	if (!info)
	74	return -ENOMEM;
	75
	76	Set flags as needed, i.e.
	77
	78	info->flags \|= FPGA_MGR_PARTIAL_RECONFIG;
	79
	80	Point to your FPGA image, such as:
	81
	82	info->sgt = &sgt;
	83
	84	Add info to region and do the programming:
	85
	86	region->info = info;
	87	ret = fpga_region_program_fpga(region);
	88
	89	Then enumerate whatever hardware has appeared in the FPGA.
	90
	91	--
	92	[1] ../devicetree/bindings/fpga/fpga-region.txt
	93	[2] ./fpga-mgr.txt
	94	[3] ../../drivers/fpga/of-fpga-region.c