cachepc-linux

Fork of AMDESE/linux with modifications for CachePC side-channel attack
git clone https://git.sinitax.com/sinitax/cachepc-linux
Log | Files | Refs | README | LICENSE | sfeed.txt

fpga-programming.rst (3001B)

      1In-kernel API for FPGA Programming
      2==================================
      3
      4Overview
      5--------
      6
      7The in-kernel API for FPGA programming is a combination of APIs from
      8FPGA manager, bridge, and regions.  The actual function used to
      9trigger FPGA programming is fpga_region_program_fpga().
     10
     11fpga_region_program_fpga() uses functionality supplied by
     12the 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:expr:`fpga_region->info`.
     19 * re-enable the bridges
     20 * release the locks
     21
     22The struct fpga_image_info specifies what FPGA image to program.  It is
     23allocated/freed by fpga_image_info_alloc() and freed with
     24fpga_image_info_free()
     25
     26How to program an FPGA using a region
     27-------------------------------------
     28
     29When the FPGA region driver probed, it was given a pointer to an FPGA manager
     30driver so it knows which manager to use.  The region also either has a list of
     31bridges to control during programming or it has a pointer to a function that
     32will 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
     84API for programming an FPGA
     85---------------------------
     86
     87* fpga_region_program_fpga() -  Program an FPGA
     88* fpga_image_info() -  Specifies what FPGA image to program
     89* fpga_image_info_alloc() -  Allocate an FPGA image info struct
     90* 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
     95FPGA 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