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

   1 FPGA Region
   2 ===========
   3
   4 Overview
   5 --------
   6
   7 This document is meant to be an 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 if for partial
  35    reconfiguration.
  36
  37 How to program a FPGA using a region
  38 ------------------------------------
  39
  40 First, allocate the info struct::
  41
  42         info = fpga_image_info_alloc(dev);
  43         if (!info)
  44                 return -ENOMEM;
  45
  46 Set flags as needed, i.e.::
  47
  48         info->flags |= FPGA_MGR_PARTIAL_RECONFIG;
  49
  50 Point to your FPGA image, such as::
  51
  52         info->sgt = &sgt;
  53
  54 Add info to region and do the programming::
  55
  56         region->info = info;
  57         ret = fpga_region_program_fpga(region);
  58
  59 :c:func:`fpga_region_program_fpga()` operates on info passed in the
  60 fpga_image_info (region->info).  This function will attempt to:
  61
  62  * lock the region's mutex
  63  * lock the region's FPGA manager
  64  * build a list of FPGA bridges if a method has been specified to do so
  65  * disable the bridges
  66  * program the FPGA
  67  * re-enable the bridges
  68  * release the locks
  69
  70 Then you will want to enumerate whatever hardware has appeared in the FPGA.
  71
  72 How to add a new FPGA region
  73 ----------------------------
  74
  75 An example of usage can be seen in the probe function of [#f2]_.
  76
  77 .. [#f1] ../devicetree/bindings/fpga/fpga-region.txt
  78 .. [#f2] ../../drivers/fpga/of-fpga-region.c
  79
  80 API to program a FGPA
  81 ---------------------
  82
  83 .. kernel-doc:: drivers/fpga/fpga-region.c
  84    :functions: fpga_region_program_fpga
  85
  86 API to add a new FPGA region
  87 ----------------------------
  88
  89 .. kernel-doc:: include/linux/fpga/fpga-region.h
  90    :functions: fpga_region
  91
  92 .. kernel-doc:: drivers/fpga/fpga-region.c
  93    :functions: fpga_region_create
  94
  95 .. kernel-doc:: drivers/fpga/fpga-region.c
  96    :functions: fpga_region_free
  97
  98 .. kernel-doc:: drivers/fpga/fpga-region.c
  99    :functions: fpga_region_register
 100
 101 .. kernel-doc:: drivers/fpga/fpga-region.c
 102    :functions: fpga_region_unregister