fpga-region.rst 3.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103
  1. FPGA Region
  2. ===========
  3. Overview
  4. --------
  5. This document is meant to be a brief overview of the FPGA region API usage. A
  6. more conceptual look at regions can be found in the Device Tree binding
  7. document [#f1]_.
  8. For the purposes of this API document, let's just say that a region associates
  9. an FPGA Manager and a bridge (or bridges) with a reprogrammable region of an
  10. FPGA or the whole FPGA. The API provides a way to register a region and to
  11. program a region.
  12. Currently the only layer above fpga-region.c in the kernel is the Device Tree
  13. support (of-fpga-region.c) described in [#f1]_. The DT support layer uses regions
  14. to program the FPGA and then DT to handle enumeration. The common region code
  15. is intended to be used by other schemes that have other ways of accomplishing
  16. enumeration after programming.
  17. An fpga-region can be set up to know the following things:
  18. * which FPGA manager to use to do the programming
  19. * which bridges to disable before programming and enable afterwards.
  20. Additional info needed to program the FPGA image is passed in the struct
  21. fpga_image_info including:
  22. * pointers to the image as either a scatter-gather buffer, a contiguous
  23. buffer, or the name of firmware file
  24. * flags indicating specifics such as whether the image is for partial
  25. reconfiguration.
  26. How to add a new FPGA region
  27. ----------------------------
  28. An example of usage can be seen in the probe function of [#f2]_.
  29. .. [#f1] ../devicetree/bindings/fpga/fpga-region.txt
  30. .. [#f2] ../../drivers/fpga/of-fpga-region.c
  31. API to add a new FPGA region
  32. ----------------------------
  33. * struct fpga_region — The FPGA region struct
  34. * devm_fpga_region_create() — Allocate and init a region struct
  35. * fpga_region_register() — Register an FPGA region
  36. * fpga_region_unregister() — Unregister an FPGA region
  37. The FPGA region's probe function will need to get a reference to the FPGA
  38. Manager it will be using to do the programming. This usually would happen
  39. during the region's probe function.
  40. * fpga_mgr_get() — Get a reference to an FPGA manager, raise ref count
  41. * of_fpga_mgr_get() — Get a reference to an FPGA manager, raise ref count,
  42. given a device node.
  43. * fpga_mgr_put() — Put an FPGA manager
  44. The FPGA region will need to specify which bridges to control while programming
  45. the FPGA. The region driver can build a list of bridges during probe time
  46. (:c:expr:`fpga_region->bridge_list`) or it can have a function that creates
  47. the list of bridges to program just before programming
  48. (:c:expr:`fpga_region->get_bridges`). The FPGA bridge framework supplies the
  49. following APIs to handle building or tearing down that list.
  50. * fpga_bridge_get_to_list() — Get a ref of an FPGA bridge, add it to a
  51. list
  52. * of_fpga_bridge_get_to_list() — Get a ref of an FPGA bridge, add it to a
  53. list, given a device node
  54. * fpga_bridges_put() — Given a list of bridges, put them
  55. .. kernel-doc:: include/linux/fpga/fpga-region.h
  56. :functions: fpga_region
  57. .. kernel-doc:: drivers/fpga/fpga-region.c
  58. :functions: devm_fpga_region_create
  59. .. kernel-doc:: drivers/fpga/fpga-region.c
  60. :functions: fpga_region_register
  61. .. kernel-doc:: drivers/fpga/fpga-region.c
  62. :functions: fpga_region_unregister
  63. .. kernel-doc:: drivers/fpga/fpga-mgr.c
  64. :functions: fpga_mgr_get
  65. .. kernel-doc:: drivers/fpga/fpga-mgr.c
  66. :functions: of_fpga_mgr_get
  67. .. kernel-doc:: drivers/fpga/fpga-mgr.c
  68. :functions: fpga_mgr_put
  69. .. kernel-doc:: drivers/fpga/fpga-bridge.c
  70. :functions: fpga_bridge_get_to_list
  71. .. kernel-doc:: drivers/fpga/fpga-bridge.c
  72. :functions: of_fpga_bridge_get_to_list
  73. .. kernel-doc:: drivers/fpga/fpga-bridge.c
  74. :functions: fpga_bridges_put