113 lines · plain
1FPGA Region2===========3 4Overview5--------6 7This document is meant to be a brief overview of the FPGA region API usage. A8more conceptual look at regions can be found in the Device Tree binding9document [#f1]_.10 11For the purposes of this API document, let's just say that a region associates12an FPGA Manager and a bridge (or bridges) with a reprogrammable region of an13FPGA or the whole FPGA. The API provides a way to register a region and to14program a region.15 16Currently the only layer above fpga-region.c in the kernel is the Device Tree17support (of-fpga-region.c) described in [#f1]_. The DT support layer uses regions18to program the FPGA and then DT to handle enumeration. The common region code19is intended to be used by other schemes that have other ways of accomplishing20enumeration 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 programming25 26 * which bridges to disable before programming and enable afterwards.27 28Additional info needed to program the FPGA image is passed in the struct29fpga_image_info including:30 31 * pointers to the image as either a scatter-gather buffer, a contiguous32 buffer, or the name of firmware file33 34 * flags indicating specifics such as whether the image is for partial35 reconfiguration.36 37How to add a new FPGA region38----------------------------39 40An example of usage can be seen in the probe function of [#f2]_.41 42.. [#f1] ../devicetree/bindings/fpga/fpga-region.txt43.. [#f2] ../../drivers/fpga/of-fpga-region.c44 45API to add a new FPGA region46----------------------------47 48* struct fpga_region - The FPGA region struct49* struct fpga_region_info - Parameter structure for __fpga_region_register_full()50* __fpga_region_register_full() - Create and register an FPGA region using the51 fpga_region_info structure to provide the full flexibility of options52* __fpga_region_register() - Create and register an FPGA region using standard53 arguments54* fpga_region_unregister() - Unregister an FPGA region55 56Helper macros ``fpga_region_register()`` and ``fpga_region_register_full()``57automatically set the module that registers the FPGA region as the owner.58 59The FPGA region's probe function will need to get a reference to the FPGA60Manager it will be using to do the programming. This usually would happen61during the region's probe function.62 63* fpga_mgr_get() - Get a reference to an FPGA manager, raise ref count64* of_fpga_mgr_get() - Get a reference to an FPGA manager, raise ref count,65 given a device node.66* fpga_mgr_put() - Put an FPGA manager67 68The FPGA region will need to specify which bridges to control while programming69the FPGA. The region driver can build a list of bridges during probe time70(:c:expr:`fpga_region->bridge_list`) or it can have a function that creates71the list of bridges to program just before programming72(:c:expr:`fpga_region->get_bridges`). The FPGA bridge framework supplies the73following APIs to handle building or tearing down that list.74 75* fpga_bridge_get_to_list() - Get a ref of an FPGA bridge, add it to a76 list77* of_fpga_bridge_get_to_list() - Get a ref of an FPGA bridge, add it to a78 list, given a device node79* fpga_bridges_put() - Given a list of bridges, put them80 81.. kernel-doc:: include/linux/fpga/fpga-region.h82 :functions: fpga_region83 84.. kernel-doc:: include/linux/fpga/fpga-region.h85 :functions: fpga_region_info86 87.. kernel-doc:: drivers/fpga/fpga-region.c88 :functions: __fpga_region_register_full89 90.. kernel-doc:: drivers/fpga/fpga-region.c91 :functions: __fpga_region_register92 93.. kernel-doc:: drivers/fpga/fpga-region.c94 :functions: fpga_region_unregister95 96.. kernel-doc:: drivers/fpga/fpga-mgr.c97 :functions: fpga_mgr_get98 99.. kernel-doc:: drivers/fpga/fpga-mgr.c100 :functions: of_fpga_mgr_get101 102.. kernel-doc:: drivers/fpga/fpga-mgr.c103 :functions: fpga_mgr_put104 105.. kernel-doc:: drivers/fpga/fpga-bridge.c106 :functions: fpga_bridge_get_to_list107 108.. kernel-doc:: drivers/fpga/fpga-bridge.c109 :functions: of_fpga_bridge_get_to_list110 111.. kernel-doc:: drivers/fpga/fpga-bridge.c112 :functions: fpga_bridges_put113