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 The FPGA region's probe function will need to get a reference to the FPGA
  57 Manager it will be using to do the programming.  This usually would happen
  58 during the region's probe function.
  59
  60 * fpga_mgr_get() - Get a reference to an FPGA manager, raise ref count
  61 * of_fpga_mgr_get() -  Get a reference to an FPGA manager, raise ref count,
  62   given a device node.
  63 * fpga_mgr_put() - Put an FPGA manager
  64
  65 The FPGA region will need to specify which bridges to control while programming
  66 the FPGA.  The region driver can build a list of bridges during probe time
  67 (:c:expr:`fpga_region->bridge_list`) or it can have a function that creates
  68 the list of bridges to program just before programming
  69 (:c:expr:`fpga_region->get_bridges`).  The FPGA bridge framework supplies the
  70 following APIs to handle building or tearing down that list.
  71
  72 * fpga_bridge_get_to_list() - Get a ref of an FPGA bridge, add it to a
  73   list
  74 * of_fpga_bridge_get_to_list() - Get a ref of an FPGA bridge, add it to a
  75   list, given a device node
  76 * fpga_bridges_put() - Given a list of bridges, put them
  77
  78 .. kernel-doc:: include/linux/fpga/fpga-region.h
  79    :functions: fpga_region
  80
  81 .. kernel-doc:: include/linux/fpga/fpga-region.h
  82    :functions: fpga_region_info
  83
  84 .. kernel-doc:: drivers/fpga/fpga-region.c
  85    :functions: fpga_region_register_full
  86
  87 .. kernel-doc:: drivers/fpga/fpga-region.c
  88    :functions: fpga_region_register
  89
  90 .. kernel-doc:: drivers/fpga/fpga-region.c
  91    :functions: fpga_region_unregister
  92
  93 .. kernel-doc:: drivers/fpga/fpga-mgr.c
  94    :functions: fpga_mgr_get
  95
  96 .. kernel-doc:: drivers/fpga/fpga-mgr.c
  97    :functions: of_fpga_mgr_get
  98
  99 .. kernel-doc:: drivers/fpga/fpga-mgr.c
 100    :functions: fpga_mgr_put
 101
 102 .. kernel-doc:: drivers/fpga/fpga-bridge.c
 103    :functions: fpga_bridge_get_to_list
 104
 105 .. kernel-doc:: drivers/fpga/fpga-bridge.c
 106    :functions: of_fpga_bridge_get_to_list
 107
 108 .. kernel-doc:: drivers/fpga/fpga-bridge.c
 109    :functions: fpga_bridges_put