fpga-programming.rst 2.9 KB

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