Skip to content

L
linux
Commit 547b822c authored by Alan Tull's avatar Alan Tull Committed by Greg Kroah-Hartman
Browse files
Options

documentation: fpga: move fpga-mgr.txt to driver-api 

Move Documentation/fpga/fpga-mgr.txt to driver-api/fpga/fpga-mgr.rst
and:
 - Add to driver-api/fpga/index.rst
 - Format changes so documentation builds cleanly.
 - Minor rewrites that make the doc flow better as ReST documentation.
   - Such as moving API reference to end of doc
 - Change API reference section to refer to kernel-doc documentation in
   fpga-mgr.c driver code rather than statically defining each function.
Signed-off-by: default avatarAlan Tull <atull@kernel.org>
Signed-off-by: default avatarGreg Kroah-Hartman <gregkh@linuxfoundation.org>
parent 66c472cd
Show whitespace changes
Inline Side-by-side
Showing with 221 additions and 0 deletions
Documentation/fpga/fpga-mgr.txt → Documentation/driver-api/fpga/fpga-mgr.rst
View file @ 547b822c
FPGA Manager Core
Alan Tull 2015
FPGA Manager
============
Overview
========
--------
The FPGA manager core exports a set of functions for programming an FPGA with
an image. The API is manufacturer agnostic. All manufacturer specifics are
......@@ -21,198 +20,201 @@ fpga_image_info). This struct contains parameters such as pointers to the
FPGA image as well as image-specific particulars such as whether the image was
built for full or partial reconfiguration.
API Functions:
==============
How to support a new FPGA device
--------------------------------
To program the FPGA:
--------------------
To add another FPGA manager, write a driver that implements a set of ops. The
probe function calls fpga_mgr_register(), such as::
int fpga_mgr_load(struct fpga_manager *mgr,
struct fpga_image_info *info);
static const struct fpga_manager_ops socfpga_fpga_ops = {
.write_init = socfpga_fpga_ops_configure_init,
.write = socfpga_fpga_ops_configure_write,
.write_complete = socfpga_fpga_ops_configure_complete,
.state = socfpga_fpga_ops_state,
};
Load the FPGA from an image which is indicated in the info. If successful,
the FPGA ends up in operating mode. Return 0 on success or a negative error
code.
static int socfpga_fpga_probe(struct platform_device *pdev)
{
struct device *dev = &pdev->dev;
struct socfpga_fpga_priv *priv;
struct fpga_manager *mgr;
int ret;
To allocate or free a struct fpga_image_info:
---------------------------------------------
priv = devm_kzalloc(dev, sizeof(*priv), GFP_KERNEL);
if (!priv)
return -ENOMEM;
struct fpga_image_info *fpga_image_info_alloc(struct device *dev);
/*
* do ioremaps, get interrupts, etc. and save
* them in priv
*/
void fpga_image_info_free(struct fpga_image_info *info);
mgr = fpga_mgr_create(dev, "Altera SOCFPGA FPGA Manager",
&socfpga_fpga_ops, priv);
if (!mgr)
return -ENOMEM;
To get/put a reference to a FPGA manager:
-----------------------------------------
platform_set_drvdata(pdev, mgr);
struct fpga_manager *of_fpga_mgr_get(struct device_node *node);
struct fpga_manager *fpga_mgr_get(struct device *dev);
void fpga_mgr_put(struct fpga_manager *mgr);
ret = fpga_mgr_register(mgr);
if (ret)
fpga_mgr_free(mgr);
Given a DT node or device, get a reference to a FPGA manager. This pointer
can be saved until you are ready to program the FPGA. fpga_mgr_put releases
the reference.
return ret;
}
static int socfpga_fpga_remove(struct platform_device *pdev)
{
struct fpga_manager *mgr = platform_get_drvdata(pdev);
To get exclusive control of a FPGA manager:
-------------------------------------------
fpga_mgr_unregister(mgr);
int fpga_mgr_lock(struct fpga_manager *mgr);
void fpga_mgr_unlock(struct fpga_manager *mgr);
return 0;
}
The user should call fpga_mgr_lock and verify that it returns 0 before
attempting to program the FPGA. Likewise, the user should call
fpga_mgr_unlock when done programming the FPGA.
To alloc/free a FPGA manager struct:
------------------------------------
The ops will implement whatever device specific register writes are needed to
do the programming sequence for this particular FPGA. These ops return 0 for
success or negative error codes otherwise.
struct fpga_manager *fpga_mgr_create(struct device *dev,
const char *name,
const struct fpga_manager_ops *mops,
void *priv);
void fpga_mgr_free(struct fpga_manager *mgr);
The programming sequence is::
1. .write_init
2. .write or .write_sg (may be called once or multiple times)
3. .write_complete
To register or unregister the low level FPGA-specific driver:
-------------------------------------------------------------
The .write_init function will prepare the FPGA to receive the image data. The
buffer passed into .write_init will be atmost .initial_header_size bytes long,
if the whole bitstream is not immediately available then the core code will
buffer up at least this much before starting.
int fpga_mgr_register(struct fpga_manager *mgr);
The .write function writes a buffer to the FPGA. The buffer may be contain the
whole FPGA image or may be a smaller chunk of an FPGA image. In the latter
case, this function is called multiple times for successive chunks. This interface
is suitable for drivers which use PIO.
void fpga_mgr_unregister(struct fpga_manager *mgr);
The .write_sg version behaves the same as .write except the input is a sg_table
scatter list. This interface is suitable for drivers which use DMA.
Use of these functions is described below in "How To Support a new FPGA
device."
The .write_complete function is called after all the image has been written
to put the FPGA into operating mode.
The ops include a .state function which will read the hardware FPGA manager and
return a code of type enum fpga_mgr_states. It doesn't result in a change in
hardware state.
How to write an image buffer to a supported FPGA
================================================
#include <linux/fpga/fpga-mgr.h>
------------------------------------------------
Some sample code::
struct fpga_manager *mgr;
struct fpga_image_info *info;
int ret;
#include <linux/fpga/fpga-mgr.h>
/*
struct fpga_manager *mgr;
struct fpga_image_info *info;
int ret;
/*
* Get a reference to FPGA manager. The manager is not locked, so you can
* hold onto this reference without it preventing programming.
*
* This example uses the device node of the manager. Alternatively, use
* fpga_mgr_get(dev) instead if you have the device.
*/
mgr = of_fpga_mgr_get(mgr_node);
mgr = of_fpga_mgr_get(mgr_node);
/* struct with information about the FPGA image to program. */
info = fpga_image_info_alloc(dev);
/* struct with information about the FPGA image to program. */
info = fpga_image_info_alloc(dev);
/* flags indicates whether to do full or partial reconfiguration */
info->flags = FPGA_MGR_PARTIAL_RECONFIG;
/* flags indicates whether to do full or partial reconfiguration */
info->flags = FPGA_MGR_PARTIAL_RECONFIG;
/*
/*
* At this point, indicate where the image is. This is pseudo-code; you're
* going to use one of these three.
*/
if (image is in a scatter gather table) {
if (image is in a scatter gather table) {
info->sgt = [your scatter gather table]
} else if (image is in a buffer) {
} else if (image is in a buffer) {
info->buf = [your image buffer]
info->count = [image buffer size]
} else if (image is in a firmware file) {
} else if (image is in a firmware file) {
info->firmware_name = devm_kstrdup(dev, firmware_name, GFP_KERNEL);
}
}
/* Get exclusive control of FPGA manager */
ret = fpga_mgr_lock(mgr);
/* Get exclusive control of FPGA manager */
ret = fpga_mgr_lock(mgr);
/* Load the buffer to the FPGA */
ret = fpga_mgr_buf_load(mgr, &info, buf, count);
/* Load the buffer to the FPGA */
ret = fpga_mgr_buf_load(mgr, &info, buf, count);
/* Release the FPGA manager */
fpga_mgr_unlock(mgr);
fpga_mgr_put(mgr);
/* Release the FPGA manager */
fpga_mgr_unlock(mgr);
fpga_mgr_put(mgr);
/* Deallocate the image info if you're done with it */
fpga_image_info_free(info);
/* Deallocate the image info if you're done with it */
fpga_image_info_free(info);
How to support a new FPGA device
================================
To add another FPGA manager, write a driver that implements a set of ops. The
probe function calls fpga_mgr_register(), such as:
API for implementing a new FPGA Manager driver
----------------------------------------------
static const struct fpga_manager_ops socfpga_fpga_ops = {
.write_init = socfpga_fpga_ops_configure_init,
.write = socfpga_fpga_ops_configure_write,
.write_complete = socfpga_fpga_ops_configure_complete,
.state = socfpga_fpga_ops_state,
};
.. kernel-doc:: include/linux/fpga/fpga-mgr.h
:functions: fpga_manager
static int socfpga_fpga_probe(struct platform_device *pdev)
{
struct device *dev = &pdev->dev;
struct socfpga_fpga_priv *priv;
struct fpga_manager *mgr;
int ret;
.. kernel-doc:: include/linux/fpga/fpga-mgr.h
:functions: fpga_manager_ops
priv = devm_kzalloc(dev, sizeof(*priv), GFP_KERNEL);
if (!priv)
return -ENOMEM;
.. kernel-doc:: drivers/fpga/fpga-mgr.c
:functions: fpga_mgr_create
/* ... do ioremaps, get interrupts, etc. and save
them in priv... */
.. kernel-doc:: drivers/fpga/fpga-mgr.c
:functions: fpga_mgr_free
mgr = fpga_mgr_create(dev, "Altera SOCFPGA FPGA Manager",
&socfpga_fpga_ops, priv);
if (!mgr)
return -ENOMEM;
.. kernel-doc:: drivers/fpga/fpga-mgr.c
:functions: fpga_mgr_register
platform_set_drvdata(pdev, mgr);
.. kernel-doc:: drivers/fpga/fpga-mgr.c
:functions: fpga_mgr_unregister
ret = fpga_mgr_register(mgr);
if (ret)
fpga_mgr_free(mgr);
API for programming a FPGA
--------------------------
return ret;
}
.. kernel-doc:: include/linux/fpga/fpga-mgr.h
:functions: fpga_image_info
static int socfpga_fpga_remove(struct platform_device *pdev)
{
struct fpga_manager *mgr = platform_get_drvdata(pdev);
.. kernel-doc:: include/linux/fpga/fpga-mgr.h
:functions: fpga_mgr_states
fpga_mgr_unregister(mgr);
.. kernel-doc:: drivers/fpga/fpga-mgr.c
:functions: fpga_image_info_alloc
return 0;
}
.. kernel-doc:: drivers/fpga/fpga-mgr.c
:functions: fpga_image_info_free
.. kernel-doc:: drivers/fpga/fpga-mgr.c
:functions: of_fpga_mgr_get
The ops will implement whatever device specific register writes are needed to
do the programming sequence for this particular FPGA. These ops return 0 for
success or negative error codes otherwise.
.. kernel-doc:: drivers/fpga/fpga-mgr.c
:functions: fpga_mgr_get
The programming sequence is:
1. .write_init
2. .write or .write_sg (may be called once or multiple times)
3. .write_complete
.. kernel-doc:: drivers/fpga/fpga-mgr.c
:functions: fpga_mgr_put
The .write_init function will prepare the FPGA to receive the image data. The
buffer passed into .write_init will be atmost .initial_header_size bytes long,
if the whole bitstream is not immediately available then the core code will
buffer up at least this much before starting.
.. kernel-doc:: drivers/fpga/fpga-mgr.c
:functions: fpga_mgr_lock
The .write function writes a buffer to the FPGA. The buffer may be contain the
whole FPGA image or may be a smaller chunk of an FPGA image. In the latter
case, this function is called multiple times for successive chunks. This interface
is suitable for drivers which use PIO.
.. kernel-doc:: drivers/fpga/fpga-mgr.c
:functions: fpga_mgr_unlock
The .write_sg version behaves the same as .write except the input is a sg_table
scatter list. This interface is suitable for drivers which use DMA.
.. kernel-doc:: include/linux/fpga/fpga-mgr.h
:functions: fpga_mgr_states
The .write_complete function is called after all the image has been written
to put the FPGA into operating mode.
Note - use :c:func:`fpga_region_program_fpga()` instead of :c:func:`fpga_mgr_load()`
The ops include a .state function which will read the hardware FPGA manager and
return a code of type enum fpga_mgr_states. It doesn't result in a change in
hardware state.
.. kernel-doc:: drivers/fpga/fpga-mgr.c
:functions: fpga_mgr_load
Documentation/driver-api/fpga/index.rst
View file @ 547b822c
......@@ -8,3 +8,4 @@ FPGA Subsystem
:maxdepth: 2
intro
fpga-mgr
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7