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