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

   1 In-kernel API for FPGA Programming
   2 ==================================
   3
   4 Overview
   5 --------
   6
   7 The in-kernel API for FPGA programming is a combination of APIs from
   8 FPGA manager, bridge, and regions.  The actual function used to
   9 trigger FPGA programming is :c:func:`fpga_region_program_fpga()`.
  10
  11 :c:func:`fpga_region_program_fpga()` uses functionality supplied by
  12 the FPGA manager and bridges.  It will:
  13
  14  * lock the region's mutex
  15  * lock the mutex of the region's FPGA manager
  16  * build a list of FPGA bridges if a method has been specified to do so
  17  * disable the bridges
  18  * program the FPGA using info passed in :c:member:`fpga_region->info`.
  19  * re-enable the bridges
  20  * release the locks
  21
  22 The struct fpga_image_info specifies what FPGA image to program.  It is
  23 allocated/freed by :c:func:`fpga_image_info_alloc()` and freed with
  24 :c:func:`fpga_image_info_free()`
  25
  26 How to program an FPGA using a region
  27 -------------------------------------
  28
  29 When the FPGA region driver probed, it was given a pointer to an FPGA manager
  30 driver so it knows which manager to use.  The region also either has a list of
  31 bridges to control during programming or it has a pointer to a function that
  32 will generate that list.  Here's some sample code of what to do next::
  33
  34         #include <linux/fpga/fpga-mgr.h>
  35         #include <linux/fpga/fpga-region.h>
  36
  37         struct fpga_image_info *info;
  38         int ret;
  39
  40         /*
  41          * First, alloc the struct with information about the FPGA image to
  42          * program.
  43          */
  44         info = fpga_image_info_alloc(dev);
  45         if (!info)
  46                 return -ENOMEM;
  47
  48         /* Set flags as needed, such as: */
  49         info->flags = FPGA_MGR_PARTIAL_RECONFIG;
  50
  51         /*
  52          * Indicate where the FPGA image is. This is pseudo-code; you're
  53          * going to use one of these three.
  54          */
  55         if (image is in a scatter gather table) {
  56
  57                 info->sgt = [your scatter gather table]
  58
  59         } else if (image is in a buffer) {
  60
  61                 info->buf = [your image buffer]
  62                 info->count = [image buffer size]
  63
  64         } else if (image is in a firmware file) {
  65
  66                 info->firmware_name = devm_kstrdup(dev, firmware_name,
  67                                                    GFP_KERNEL);
  68
  69         }
  70
  71         /* Add info to region and do the programming */
  72         region->info = info;
  73         ret = fpga_region_program_fpga(region);
  74
  75         /* Deallocate the image info if you're done with it */
  76         region->info = NULL;
  77         fpga_image_info_free(info);
  78
  79         if (ret)
  80                 return ret;
  81
  82         /* Now enumerate whatever hardware has appeared in the FPGA. */
  83
  84 API for programming an FPGA
  85 ---------------------------
  86
  87 * :c:func:`fpga_region_program_fpga` —  Program an FPGA
  88 * :c:type:`fpga_image_info` —  Specifies what FPGA image to program
  89 * :c:func:`fpga_image_info_alloc()` —  Allocate an FPGA image info struct
  90 * :c:func:`fpga_image_info_free()` —  Free an FPGA image info struct
  91
  92 .. kernel-doc:: drivers/fpga/fpga-region.c
  93    :functions: fpga_region_program_fpga
  94
  95 FPGA Manager flags
  96
  97 .. kernel-doc:: include/linux/fpga/fpga-mgr.h
  98    :doc: FPGA Manager flags
  99
 100 .. kernel-doc:: include/linux/fpga/fpga-mgr.h
 101    :functions: fpga_image_info
 102
 103 .. kernel-doc:: drivers/fpga/fpga-mgr.c
 104    :functions: fpga_image_info_alloc
 105
 106 .. kernel-doc:: drivers/fpga/fpga-mgr.c
 107    :functions: fpga_image_info_free