linux-stable.git/Documentation/driver-api/fpga, branch linux-5.15.y

fpga: region: add owner module and take its refcount

2024-06-16T11:39:38+00:00

[ Upstream commit b7c0e1ecee403a43abc89eb3e75672b01ff2ece9 ]

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: 0fa20cdfcc1f ("fpga: fpga-region: device tree control for FPGA")
Suggested-by: Greg Kroah-Hartman 
Suggested-by: Xu Yilun 
Reviewed-by: Russ Weight 
Signed-off-by: Marco Pagani 
Acked-by: Xu Yilun 
Link: https://lore.kernel.org/r/20240419083601.77403-1-marpagan@redhat.com
Signed-off-by: Xu Yilun 
Signed-off-by: Sasha Levin

fpga: region: Use standard dev_release for class driver

2024-06-16T11:39:38+00:00

[ Upstream commit 8886a579744fbfa53e69aa453ed10ae3b1f9abac ]

The FPGA region class driver data structure is being treated as a
managed resource instead of using the standard dev_release call-back
function to release the class data structure. This change removes the
managed resource code and combines the create() and register()
functions into a single register() or register_full() function.

The register_full() function accepts an info data structure to provide
flexibility in passing optional parameters. The register() function
supports the current parameter list for users that don't require the
use of optional parameters.

Signed-off-by: Russ Weight 
Reviewed-by: Xu Yilun 
Acked-by: Xu Yilun 
Signed-off-by: Moritz Fischer 
Stable-dep-of: b7c0e1ecee40 ("fpga: region: add owner module and take its refcount")
Signed-off-by: Sasha Levin

docs: driver-api: fpga: avoid using UTF-8 chars

2021-07-22T02:54:21+00:00

While UTF-8 characters can be used at the Linux documentation,
the best is to use them only when ASCII doesn't offer a good replacement.
So, replace the occurences of the following UTF-8 characters:

	- U+2014 ('—'): EM DASH

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Moritz Fischer

docs: fpga: replace :c:member: macros

2020-10-15T05:49:43+00:00

Those macros are not doing the right thing with Sphinx 3,
causing parse errors:

	./Documentation/driver-api/fpga/fpga-mgr.rst:104: WARNING: Unparseable C cross-reference: 'fpga_manager->state'
	Invalid C declaration: Expected end of definition. [error at 12]
	  fpga_manager->state
	  ------------^
	./Documentation/driver-api/fpga/fpga-programming.rst:18: WARNING: Unparseable C cross-reference: 'fpga_region->info'
	Invalid C declaration: Expected end of definition. [error at 11]
	  fpga_region->info
	  -----------^
	./Documentation/driver-api/fpga/fpga-region.rst:62: WARNING: Unparseable C cross-reference: 'fpga_region->bridge_list'
	Invalid C declaration: Expected end of definition. [error at 11]
	  fpga_region->bridge_list
	  -----------^
	./Documentation/driver-api/fpga/fpga-region.rst:62: WARNING: Unparseable C cross-reference: 'fpga_region->get_bridges'
	Invalid C declaration: Expected end of definition. [error at 11]
	  fpga_region->get_bridges
	  -----------^

Replace them by :c:expr:, with does what's desired.

Reviewed-by: Moritz Fischer 
Signed-off-by: Mauro Carvalho Chehab

docs: get rid of :c:type explicit declarations for structs

2020-10-15T05:49:40+00:00

The :c:type:`foo` only works properly with structs before
Sphinx 3.x.

On Sphinx 3.x, structs should now be declared using the
.. c:struct, and referenced via :c:struct tag.

As we now have the automarkup.py macro, that automatically
convert:
	struct foo

into cross-references, let's get rid of that, solving
several warnings when building docs with Sphinx 3.x.

Reviewed-by: André Almeida  # blk-mq.rst
Reviewed-by: Takashi Iwai  # sound
Reviewed-by: Mike Rapoport 
Reviewed-by: Greg Kroah-Hartman 
Signed-off-by: Mauro Carvalho Chehab

Fpga: Documentation: Replace deprecated :c:func: Usage

2020-08-24T23:19:06+00:00

Replace :c:func: with func() as the previous usage is deprecated.

Signed-off-by: Puranjay Mohan 
Link: https://lore.kernel.org/r/20200812180224.24810-1-puranjay12@gmail.com
Signed-off-by: Jonathan Corbet

docs: fpga: document programming fpgas using regions

2018-10-16T09:13:50+00:00

Clarify the intention that interfaces and upper layers use
regions rather than managers directly.

Rearrange API documentation to better group the API functions
used to create FPGA mgr/bridge/regions and the API used for
programming FPGAs.

Signed-off-by: Alan Tull 
Suggested-by: Federico Vaga 
Acked-by: Moritz Fischer 
Signed-off-by: Greg Kroah-Hartman

fpga: add devm_fpga_region_create

2018-10-16T09:13:50+00:00

Add devm_fpga_region_create() which is the
managed version of fpga_region_create().

Change current region drivers to use
devm_fpga_region_create().

Signed-off-by: Alan Tull 
Suggested-by: Federico Vaga 
Acked-by: Moritz Fischer 
Signed-off-by: Greg Kroah-Hartman

fpga: bridge: add devm_fpga_bridge_create

2018-10-16T09:13:50+00:00

Add devm_fpga_bridge_create() which is the managed
version of fpga_bridge_create().

Change current bridge drivers to use
devm_fpga_bridge_create().

Signed-off-by: Alan Tull 
Suggested-by: Federico Vaga 
Acked-by: Moritz Fischer 
Signed-off-by: Greg Kroah-Hartman

fpga: mgr: add devm_fpga_mgr_create

2018-10-16T09:13:50+00:00

Add devm_fpga_mgr_create() which is the managed
version of fpga_mgr_create().

Change current FPGA manager drivers to use
devm_fpga_mgr_create()

Signed-off-by: Alan Tull 
Suggested-by: Federico Vaga 
Acked-by: Moritz Fischer 
Signed-off-by: Greg Kroah-Hartman