0001 FPGA Region
0002 ===========
0003
0004 Overview
0005 --------
0006
0007 This document is meant to be a brief overview of the FPGA region API usage. A
0008 more conceptual look at regions can be found in the Device Tree binding
0009 document [#f1]_.
0010
0011 For the purposes of this API document, let's just say that a region associates
0012 an FPGA Manager and a bridge (or bridges) with a reprogrammable region of an
0013 FPGA or the whole FPGA. The API provides a way to register a region and to
0014 program a region.
0015
0016 Currently the only layer above fpga-region.c in the kernel is the Device Tree
0017 support (of-fpga-region.c) described in [#f1]_. The DT support layer uses regions
0018 to program the FPGA and then DT to handle enumeration. The common region code
0019 is intended to be used by other schemes that have other ways of accomplishing
0020 enumeration after programming.
0021
0022 An fpga-region can be set up to know the following things:
0023
0024 * which FPGA manager to use to do the programming
0025
0026 * which bridges to disable before programming and enable afterwards.
0027
0028 Additional info needed to program the FPGA image is passed in the struct
0029 fpga_image_info including:
0030
0031 * pointers to the image as either a scatter-gather buffer, a contiguous
0032 buffer, or the name of firmware file
0033
0034 * flags indicating specifics such as whether the image is for partial
0035 reconfiguration.
0036
0037 How to add a new FPGA region
0038 ----------------------------
0039
0040 An example of usage can be seen in the probe function of [#f2]_.
0041
0042 .. [#f1] ../devicetree/bindings/fpga/fpga-region.txt
0043 .. [#f2] ../../drivers/fpga/of-fpga-region.c
0044
0045 API to add a new FPGA region
0046 ----------------------------
0047
0048 * struct fpga_region - The FPGA region struct
0049 * struct fpga_region_info - Parameter structure for fpga_region_register_full()
0050 * fpga_region_register_full() - Create and register an FPGA region using the
0051 fpga_region_info structure to provide the full flexibility of options
0052 * fpga_region_register() - Create and register an FPGA region using standard
0053 arguments
0054 * fpga_region_unregister() - Unregister an FPGA region
0055
0056 The FPGA region's probe function will need to get a reference to the FPGA
0057 Manager it will be using to do the programming. This usually would happen
0058 during the region's probe function.
0059
0060 * fpga_mgr_get() - Get a reference to an FPGA manager, raise ref count
0061 * of_fpga_mgr_get() - Get a reference to an FPGA manager, raise ref count,
0062 given a device node.
0063 * fpga_mgr_put() - Put an FPGA manager
0064
0065 The FPGA region will need to specify which bridges to control while programming
0066 the FPGA. The region driver can build a list of bridges during probe time
0067 (:c:expr:`fpga_region->bridge_list`) or it can have a function that creates
0068 the list of bridges to program just before programming
0069 (:c:expr:`fpga_region->get_bridges`). The FPGA bridge framework supplies the
0070 following APIs to handle building or tearing down that list.
0071
0072 * fpga_bridge_get_to_list() - Get a ref of an FPGA bridge, add it to a
0073 list
0074 * of_fpga_bridge_get_to_list() - Get a ref of an FPGA bridge, add it to a
0075 list, given a device node
0076 * fpga_bridges_put() - Given a list of bridges, put them
0077
0078 .. kernel-doc:: include/linux/fpga/fpga-region.h
0079 :functions: fpga_region
0080
0081 .. kernel-doc:: include/linux/fpga/fpga-region.h
0082 :functions: fpga_region_info
0083
0084 .. kernel-doc:: drivers/fpga/fpga-region.c
0085 :functions: fpga_region_register_full
0086
0087 .. kernel-doc:: drivers/fpga/fpga-region.c
0088 :functions: fpga_region_register
0089
0090 .. kernel-doc:: drivers/fpga/fpga-region.c
0091 :functions: fpga_region_unregister
0092
0093 .. kernel-doc:: drivers/fpga/fpga-mgr.c
0094 :functions: fpga_mgr_get
0095
0096 .. kernel-doc:: drivers/fpga/fpga-mgr.c
0097 :functions: of_fpga_mgr_get
0098
0099 .. kernel-doc:: drivers/fpga/fpga-mgr.c
0100 :functions: fpga_mgr_put
0101
0102 .. kernel-doc:: drivers/fpga/fpga-bridge.c
0103 :functions: fpga_bridge_get_to_list
0104
0105 .. kernel-doc:: drivers/fpga/fpga-bridge.c
0106 :functions: of_fpga_bridge_get_to_list
0107
0108 .. kernel-doc:: drivers/fpga/fpga-bridge.c
0109 :functions: fpga_bridges_put
