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

   1 FPGA Region
   2 ===========
   3
   4 Overview
   5 --------
   6
   7 This document is meant to be a brief overview of the FPGA region API usage.  A
   8 more conceptual look at regions can be found in the Device Tree binding
   9 document [#f1]_.
  10
  11 For the purposes of this API document, let's just say that a region associates
  12 an FPGA Manager and a bridge (or bridges) with a reprogrammable region of an
  13 FPGA or the whole FPGA.  The API provides a way to register a region and to
  14 program a region.
  15
  16 Currently the only layer above fpga-region.c in the kernel is the Device Tree
  17 support (of-fpga-region.c) described in [#f1]_.  The DT support layer uses regions
  18 to program the FPGA and then DT to handle enumeration.  The common region code
  19 is intended to be used by other schemes that have other ways of accomplishing
  20 enumeration after programming.
  21
  22 An 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
  28 Additional info needed to program the FPGA image is passed in the struct
  29 fpga_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
  37 How to add a new FPGA region
  38 ----------------------------
  39
  40 An 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
  45 API 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
  56 Helper macros ``fpga_region_register()`` and ``fpga_region_register_full()``
  57 automatically set the module that registers the FPGA region as the owner.
  58
  59 The FPGA region's probe function will need to get a reference to the FPGA
  60 Manager it will be using to do the programming.  This usually would happen
  61 during 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
  68 The FPGA region will need to specify which bridges to control while programming
  69 the 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
  71 the list of bridges to program just before programming
  72 (:c:expr:`fpga_region->get_bridges`).  The FPGA bridge framework supplies the
  73 following 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