mirror of
https://mirrors.bfsu.edu.cn/git/linux.git
synced 2024-11-11 04:18:39 +08:00
b7c0e1ecee
The current implementation of the fpga region assumes that the low-level
module registers a driver for the parent device and uses its owner pointer
to take the module's refcount. This approach is problematic since it can
lead to a null pointer dereference while attempting to get the region
during programming if the parent device does not have a driver.
To address this problem, add a module owner pointer to the fpga_region
struct and use it to take the module's refcount. Modify the functions for
registering a region to take an additional owner module parameter and
rename them to avoid conflicts. Use the old function names for helper
macros that automatically set the module that registers the region as the
owner. This ensures compatibility with existing low-level control modules
and reduces the chances of registering a region without setting the owner.
Also, update the documentation to keep it consistent with the new interface
for registering an fpga region.
Fixes: 0fa20cdfcc ("fpga: fpga-region: device tree control for FPGA")
Suggested-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Suggested-by: Xu Yilun <yilun.xu@intel.com>
Reviewed-by: Russ Weight <russ.weight@linux.dev>
Signed-off-by: Marco Pagani <marpagan@redhat.com>
Acked-by: Xu Yilun <yilun.xu@intel.com>
Link: https://lore.kernel.org/r/20240419083601.77403-1-marpagan@redhat.com
Signed-off-by: Xu Yilun <yilun.xu@linux.intel.com>
113 lines
4.0 KiB
ReStructuredText
113 lines
4.0 KiB
ReStructuredText
FPGA Region
|
|
===========
|
|
|
|
Overview
|
|
--------
|
|
|
|
This document is meant to be a brief overview of the FPGA region API usage. A
|
|
more conceptual look at regions can be found in the Device Tree binding
|
|
document [#f1]_.
|
|
|
|
For the purposes of this API document, let's just say that a region associates
|
|
an FPGA Manager and a bridge (or bridges) with a reprogrammable region of an
|
|
FPGA or the whole FPGA. The API provides a way to register a region and to
|
|
program a region.
|
|
|
|
Currently the only layer above fpga-region.c in the kernel is the Device Tree
|
|
support (of-fpga-region.c) described in [#f1]_. The DT support layer uses regions
|
|
to program the FPGA and then DT to handle enumeration. The common region code
|
|
is intended to be used by other schemes that have other ways of accomplishing
|
|
enumeration after programming.
|
|
|
|
An fpga-region can be set up to know the following things:
|
|
|
|
* which FPGA manager to use to do the programming
|
|
|
|
* which bridges to disable before programming and enable afterwards.
|
|
|
|
Additional info needed to program the FPGA image is passed in the struct
|
|
fpga_image_info including:
|
|
|
|
* pointers to the image as either a scatter-gather buffer, a contiguous
|
|
buffer, or the name of firmware file
|
|
|
|
* flags indicating specifics such as whether the image is for partial
|
|
reconfiguration.
|
|
|
|
How to add a new FPGA region
|
|
----------------------------
|
|
|
|
An example of usage can be seen in the probe function of [#f2]_.
|
|
|
|
.. [#f1] ../devicetree/bindings/fpga/fpga-region.txt
|
|
.. [#f2] ../../drivers/fpga/of-fpga-region.c
|
|
|
|
API to add a new FPGA region
|
|
----------------------------
|
|
|
|
* struct fpga_region - The FPGA region struct
|
|
* struct fpga_region_info - Parameter structure for __fpga_region_register_full()
|
|
* __fpga_region_register_full() - Create and register an FPGA region using the
|
|
fpga_region_info structure to provide the full flexibility of options
|
|
* __fpga_region_register() - Create and register an FPGA region using standard
|
|
arguments
|
|
* fpga_region_unregister() - Unregister an FPGA region
|
|
|
|
Helper macros ``fpga_region_register()`` and ``fpga_region_register_full()``
|
|
automatically set the module that registers the FPGA region as the owner.
|
|
|
|
The FPGA region's probe function will need to get a reference to the FPGA
|
|
Manager it will be using to do the programming. This usually would happen
|
|
during the region's probe function.
|
|
|
|
* fpga_mgr_get() - Get a reference to an FPGA manager, raise ref count
|
|
* of_fpga_mgr_get() - Get a reference to an FPGA manager, raise ref count,
|
|
given a device node.
|
|
* fpga_mgr_put() - Put an FPGA manager
|
|
|
|
The FPGA region will need to specify which bridges to control while programming
|
|
the FPGA. The region driver can build a list of bridges during probe time
|
|
(:c:expr:`fpga_region->bridge_list`) or it can have a function that creates
|
|
the list of bridges to program just before programming
|
|
(:c:expr:`fpga_region->get_bridges`). The FPGA bridge framework supplies the
|
|
following APIs to handle building or tearing down that list.
|
|
|
|
* fpga_bridge_get_to_list() - Get a ref of an FPGA bridge, add it to a
|
|
list
|
|
* of_fpga_bridge_get_to_list() - Get a ref of an FPGA bridge, add it to a
|
|
list, given a device node
|
|
* fpga_bridges_put() - Given a list of bridges, put them
|
|
|
|
.. kernel-doc:: include/linux/fpga/fpga-region.h
|
|
:functions: fpga_region
|
|
|
|
.. kernel-doc:: include/linux/fpga/fpga-region.h
|
|
:functions: fpga_region_info
|
|
|
|
.. kernel-doc:: drivers/fpga/fpga-region.c
|
|
:functions: __fpga_region_register_full
|
|
|
|
.. kernel-doc:: drivers/fpga/fpga-region.c
|
|
:functions: __fpga_region_register
|
|
|
|
.. kernel-doc:: drivers/fpga/fpga-region.c
|
|
:functions: fpga_region_unregister
|
|
|
|
.. kernel-doc:: drivers/fpga/fpga-mgr.c
|
|
:functions: fpga_mgr_get
|
|
|
|
.. kernel-doc:: drivers/fpga/fpga-mgr.c
|
|
:functions: of_fpga_mgr_get
|
|
|
|
.. kernel-doc:: drivers/fpga/fpga-mgr.c
|
|
:functions: fpga_mgr_put
|
|
|
|
.. kernel-doc:: drivers/fpga/fpga-bridge.c
|
|
:functions: fpga_bridge_get_to_list
|
|
|
|
.. kernel-doc:: drivers/fpga/fpga-bridge.c
|
|
:functions: of_fpga_bridge_get_to_list
|
|
|
|
.. kernel-doc:: drivers/fpga/fpga-bridge.c
|
|
:functions: fpga_bridges_put
|