Documentation/fpga/fpga-region.txt

   1 FPGA Regions
   2
   3 Alan Tull 2017
   4
   5 CONTENTS
   6  - Introduction
   7  - The FPGA region API
   8  - Usage example
   9
  10 Introduction
  11 ============
  12
  13 This document is meant to be an brief overview of the FPGA region API usage.  A
  14 more conceptual look at regions can be found in [1].
  15
  16 For the purposes of this API document, let's just say that a region associates
  17 an FPGA Manager and a bridge (or bridges) with a reprogrammable region of an
  18 FPGA or the whole FPGA.  The API provides a way to register a region and to
  19 program a region.
  20
  21 Currently the only layer above fpga-region.c in the kernel is the Device Tree
  22 support (of-fpga-region.c) described in [1].  The DT support layer uses regions
  23 to program the FPGA and then DT to handle enumeration.  The common region code
  24 is intended to be used by other schemes that have other ways of accomplishing
  25 enumeration after programming.
  26
  27 An fpga-region can be set up to know the following things:
  28 * which FPGA manager to use to do the programming
  29 * which bridges to disable before programming and enable afterwards.
  30
  31 Additional info needed to program the FPGA image is passed in the struct
  32 fpga_image_info [2] including:
  33 * pointers to the image as either a scatter-gather buffer, a contiguous
  34   buffer, or the name of firmware file
  35 * flags indicating specifics such as whether the image if for partial
  36   reconfiguration.
  37
  38 ===================
  39 The FPGA region API
  40 ===================
  41
  42 To register or unregister a region:
  43 -----------------------------------
  44
  45         int fpga_region_register(struct device *dev,
  46                                  struct fpga_region *region);
  47         int fpga_region_unregister(struct fpga_region *region);
  48
  49 An example of usage can be seen in the probe function of [3]
  50
  51 To program an FPGA:
  52 -------------------
  53         int fpga_region_program_fpga(struct fpga_region *region);
  54
  55 This function operates on info passed in the fpga_image_info
  56 (region->info).
  57
  58 This function will attempt to:
  59  * lock the region's mutex
  60  * lock the region's FPGA manager
  61  * build a list of FPGA bridges if a method has been specified to do so
  62  * disable the bridges
  63  * program the FPGA
  64  * re-enable the bridges
  65  * release the locks
  66
  67 =============
  68 Usage example
  69 =============
  70
  71 First, allocate the info struct:
  72
  73         info = fpga_image_info_alloc(dev);
  74         if (!info)
  75                 return -ENOMEM;
  76
  77 Set flags as needed, i.e.
  78
  79         info->flags |= FPGA_MGR_PARTIAL_RECONFIG;
  80
  81 Point to your FPGA image, such as:
  82
  83         info->sgt = &sgt;
  84
  85 Add info to region and do the programming:
  86
  87         region->info = info;
  88         ret = fpga_region_program_fpga(region);
  89
  90 Then enumerate whatever hardware has appeared in the FPGA.
  91
  92 --
  93 [1] ../devicetree/bindings/fpga/fpga-region.txt
  94 [2] ./fpga-mgr.txt
  95 [3] ../../drivers/fpga/of-fpga-region.c