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