1FPGA Region
  2===========
  3
  4Overview
  5--------
  6
  7This document is meant to be a brief overview of the FPGA region API usage.  A
  8more conceptual look at regions can be found in the Device Tree binding
  9document [#f1]_.
 10
 11For the purposes of this API document, let's just say that a region associates
 12an FPGA Manager and a bridge (or bridges) with a reprogrammable region of an
 13FPGA or the whole FPGA.  The API provides a way to register a region and to
 14program a region.
 15
 16Currently the only layer above fpga-region.c in the kernel is the Device Tree
 17support (of-fpga-region.c) described in [#f1]_.  The DT support layer uses regions
 18to program the FPGA and then DT to handle enumeration.  The common region code
 19is intended to be used by other schemes that have other ways of accomplishing
 20enumeration after programming.
 21
 22An fpga-region can be set up to know the following things:
 23
 24 * which FPGA manager to use to do the programming
 25
 26 * which bridges to disable before programming and enable afterwards.
 27
 28Additional info needed to program the FPGA image is passed in the struct
 29fpga_image_info including:
 30
 31 * pointers to the image as either a scatter-gather buffer, a contiguous
 32   buffer, or the name of firmware file
 33
 34 * flags indicating specifics such as whether the image is for partial
 35   reconfiguration.
 36
 37How to add a new FPGA region
 38----------------------------
 39
 40An example of usage can be seen in the probe function of [#f2]_.
 41
 42.. [#f1] ../devicetree/bindings/fpga/fpga-region.txt
 43.. [#f2] ../../drivers/fpga/of-fpga-region.c
 44
 45API to add a new FPGA region
 46----------------------------
 47
 48* struct fpga_region - The FPGA region struct
 49* struct fpga_region_info - Parameter structure for __fpga_region_register_full()
 50* __fpga_region_register_full() -  Create and register an FPGA region using the
 51  fpga_region_info structure to provide the full flexibility of options
 52* __fpga_region_register() -  Create and register an FPGA region using standard
 53  arguments
 54* fpga_region_unregister() -  Unregister an FPGA region
 55
 56Helper macros ``fpga_region_register()`` and ``fpga_region_register_full()``
 57automatically set the module that registers the FPGA region as the owner.
 58
 59The FPGA region's probe function will need to get a reference to the FPGA
 60Manager it will be using to do the programming.  This usually would happen
 61during the region's probe function.
 62
 63* fpga_mgr_get() - Get a reference to an FPGA manager, raise ref count
 64* of_fpga_mgr_get() -  Get a reference to an FPGA manager, raise ref count,
 65  given a device node.
 66* fpga_mgr_put() - Put an FPGA manager
 67
 68The FPGA region will need to specify which bridges to control while programming
 69the FPGA.  The region driver can build a list of bridges during probe time
 70(:c:expr:`fpga_region->bridge_list`) or it can have a function that creates
 71the list of bridges to program just before programming
 72(:c:expr:`fpga_region->get_bridges`).  The FPGA bridge framework supplies the
 73following APIs to handle building or tearing down that list.
 74
 75* fpga_bridge_get_to_list() - Get a ref of an FPGA bridge, add it to a
 76  list
 77* of_fpga_bridge_get_to_list() - Get a ref of an FPGA bridge, add it to a
 78  list, given a device node
 79* fpga_bridges_put() - Given a list of bridges, put them
 80
 81.. kernel-doc:: include/linux/fpga/fpga-region.h
 82   :functions: fpga_region
 83
 84.. kernel-doc:: include/linux/fpga/fpga-region.h
 85   :functions: fpga_region_info
 86
 87.. kernel-doc:: drivers/fpga/fpga-region.c
 88   :functions: __fpga_region_register_full
 89
 90.. kernel-doc:: drivers/fpga/fpga-region.c
 91   :functions: __fpga_region_register
 92
 93.. kernel-doc:: drivers/fpga/fpga-region.c
 94   :functions: fpga_region_unregister
 95
 96.. kernel-doc:: drivers/fpga/fpga-mgr.c
 97   :functions: fpga_mgr_get
 98
 99.. kernel-doc:: drivers/fpga/fpga-mgr.c
100   :functions: of_fpga_mgr_get
101
102.. kernel-doc:: drivers/fpga/fpga-mgr.c
103   :functions: fpga_mgr_put
104
105.. kernel-doc:: drivers/fpga/fpga-bridge.c
106   :functions: fpga_bridge_get_to_list
107
108.. kernel-doc:: drivers/fpga/fpga-bridge.c
109   :functions: of_fpga_bridge_get_to_list
110
111.. kernel-doc:: drivers/fpga/fpga-bridge.c
112   :functions: fpga_bridges_put