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

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>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>

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

-FPGA Regions
+FPGA Region
+===========
 
-Alan Tull 2017
-
-CONTENTS
- - Introduction
- - The FPGA region API
- - Usage example
-
-Introduction
-============
+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 [1].
+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
@@ -19,42 +14,51 @@ 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
+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.
+
+ * 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.
+fpga_image_info including:
 
-===================
-The FPGA region API
-===================
+ * pointers to the image as either a scatter-gather buffer, a contiguous
+   buffer, or the name of firmware file
 
-To register or unregister a region:
------------------------------------
+ * flags indicating specifics such as whether the image if for partial
+   reconfiguration.
 
-	int fpga_region_register(struct fpga_region *region);
-	int fpga_region_unregister(struct fpga_region *region);
+How to program a FPGA using a region
+------------------------------------
 
-An example of usage can be seen in the probe function of [3]
+First, allocate the info struct::
 
-To program an FPGA:
--------------------
-	int fpga_region_program_fpga(struct fpga_region *region);
+	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;
 
-This function operates on info passed in the fpga_image_info
-(region->info).
+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:
 
-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
@@ -63,32 +67,36 @@ This function will attempt to:
  * re-enable the bridges
  * release the locks
 
-=============
-Usage example
-=============
+Then you will want to enumerate whatever hardware has appeared in the FPGA.
 
-First, allocate the info struct:
+How to add a new FPGA region
+----------------------------
 
-	info = fpga_image_info_alloc(dev);
-	if (!info)
-		return -ENOMEM;
+An example of usage can be seen in the probe function of [#f2]_.
 
-Set flags as needed, i.e.
+.. [#f1] ../devicetree/bindings/fpga/fpga-region.txt
+.. [#f2] ../../drivers/fpga/of-fpga-region.c
 
-	info->flags |= FPGA_MGR_PARTIAL_RECONFIG;
+API to program a FGPA
+---------------------
 
-Point to your FPGA image, such as:
+.. kernel-doc:: drivers/fpga/fpga-region.c
+   :functions: fpga_region_program_fpga
 
-	info->sgt = &sgt;
+API to add a new FPGA region
+----------------------------
 
-Add info to region and do the programming:
+.. kernel-doc:: include/linux/fpga/fpga-region.h
+   :functions: fpga_region
 
-	region->info = info;
-	ret = fpga_region_program_fpga(region);
+.. kernel-doc:: drivers/fpga/fpga-region.c
+   :functions: fpga_region_create
+
+.. kernel-doc:: drivers/fpga/fpga-region.c
+   :functions: fpga_region_free
 
-Then enumerate whatever hardware has appeared in the FPGA.
+.. kernel-doc:: drivers/fpga/fpga-region.c
+   :functions: fpga_region_register
 
---
-[1] ../devicetree/bindings/fpga/fpga-region.txt
-[2] ./fpga-mgr.txt
-[3] ../../drivers/fpga/of-fpga-region.c
+.. kernel-doc:: drivers/fpga/fpga-region.c
+   :functions: fpga_region_unregister

Documentation/driver-api/fpga/index.rst

@@ -10,3 +10,4 @@ FPGA Subsystem
    intro
    fpga-mgr
    fpga-bridge
+   fpga-region