1FPGA Region 2=========== 3 4Overview 5-------- 6 7This document is meant to be a brief overview of the FPGA region API usage. A 8more conceptual look at regions can be found in the Device Tree binding 9document [#f1]_. 10 11For the purposes of this API document, let's just say that a region associates 12an FPGA Manager and a bridge (or bridges) with a reprogrammable region of an 13FPGA or the whole FPGA. The API provides a way to register a region and to 14program a region. 15 16Currently the only layer above fpga-region.c in the kernel is the Device Tree 17support (of-fpga-region.c) described in [#f1]_. The DT support layer uses regions 18to program the FPGA and then DT to handle enumeration. The common region code 19is intended to be used by other schemes that have other ways of accomplishing 20enumeration after programming. 21 22An 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 28Additional info needed to program the FPGA image is passed in the struct 29fpga_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 is for partial 35 reconfiguration. 36 37How to add a new FPGA region 38---------------------------- 39 40An example of usage can be seen in the probe function of [#f2]_. 41 42.. [#f1] ../devicetree/bindings/fpga/fpga-region.txt 43.. [#f2] ../../drivers/fpga/of-fpga-region.c 44 45API to add a new FPGA region 46---------------------------- 47 48* struct fpga_region - The FPGA region struct 49* struct fpga_region_info - Parameter structure for fpga_region_register_full() 50* fpga_region_register_full() - Create and register an FPGA region using the 51 fpga_region_info structure to provide the full flexibility of options 52* fpga_region_register() - Create and register an FPGA region using standard 53 arguments 54* fpga_region_unregister() - Unregister an FPGA region 55 56The FPGA region's probe function will need to get a reference to the FPGA 57Manager it will be using to do the programming. This usually would happen 58during the region's probe function. 59 60* fpga_mgr_get() - Get a reference to an FPGA manager, raise ref count 61* of_fpga_mgr_get() - Get a reference to an FPGA manager, raise ref count, 62 given a device node. 63* fpga_mgr_put() - Put an FPGA manager 64 65The FPGA region will need to specify which bridges to control while programming 66the FPGA. The region driver can build a list of bridges during probe time 67(:c:expr:`fpga_region->bridge_list`) or it can have a function that creates 68the list of bridges to program just before programming 69(:c:expr:`fpga_region->get_bridges`). The FPGA bridge framework supplies the 70following APIs to handle building or tearing down that list. 71 72* fpga_bridge_get_to_list() - Get a ref of an FPGA bridge, add it to a 73 list 74* of_fpga_bridge_get_to_list() - Get a ref of an FPGA bridge, add it to a 75 list, given a device node 76* fpga_bridges_put() - Given a list of bridges, put them 77 78.. kernel-doc:: include/linux/fpga/fpga-region.h 79 :functions: fpga_region 80 81.. kernel-doc:: include/linux/fpga/fpga-region.h 82 :functions: fpga_region_info 83 84.. kernel-doc:: drivers/fpga/fpga-region.c 85 :functions: fpga_region_register_full 86 87.. kernel-doc:: drivers/fpga/fpga-region.c 88 :functions: fpga_region_register 89 90.. kernel-doc:: drivers/fpga/fpga-region.c 91 :functions: fpga_region_unregister 92 93.. kernel-doc:: drivers/fpga/fpga-mgr.c 94 :functions: fpga_mgr_get 95 96.. kernel-doc:: drivers/fpga/fpga-mgr.c 97 :functions: of_fpga_mgr_get 98 99.. kernel-doc:: drivers/fpga/fpga-mgr.c 100 :functions: fpga_mgr_put 101 102.. kernel-doc:: drivers/fpga/fpga-bridge.c 103 :functions: fpga_bridge_get_to_list 104 105.. kernel-doc:: drivers/fpga/fpga-bridge.c 106 :functions: of_fpga_bridge_get_to_list 107 108.. kernel-doc:: drivers/fpga/fpga-bridge.c 109 :functions: fpga_bridges_put 110