lkml.org 
[lkml]   [2018]   [May]   [25]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    /
    SubjectRe: [PATCH 10/14] documentation: fpga: move fpga-mgr.txt to driver-api
    From
    Date
    On 05/16/2018 04:50 PM, Alan Tull wrote:
    > 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: Alan Tull <atull@kernel.org>
    > ---
    > Documentation/driver-api/fpga/fpga-mgr.rst | 220 +++++++++++++++++++++++++++++
    > Documentation/driver-api/fpga/index.rst | 1 +
    > Documentation/fpga/fpga-mgr.txt | 218 ----------------------------
    > 3 files changed, 221 insertions(+), 218 deletions(-)
    > create mode 100644 Documentation/driver-api/fpga/fpga-mgr.rst
    > delete mode 100644 Documentation/fpga/fpga-mgr.txt
    >
    > diff --git a/Documentation/driver-api/fpga/fpga-mgr.rst b/Documentation/driver-api/fpga/fpga-mgr.rst
    > new file mode 100644
    > index 0000000..bcf2dd2
    > --- /dev/null
    > +++ b/Documentation/driver-api/fpga/fpga-mgr.rst
    > @@ -0,0 +1,220 @@
    > +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
    > +hidden away in a low level driver which registers a set of ops with the core.
    > +The FPGA image data itself is very manufacturer specific, but for our purposes
    > +it's just binary data. The FPGA manager core won't parse it.
    > +
    > +The FPGA image to be programmed can be in a scatter gather list, a single
    > +contiguous buffer, or a firmware file. Because allocating contiguous kernel
    > +memory for the buffer should be avoided, users are encouraged to use a scatter
    > +gather list instead if possible.
    > +
    > +The particulars for programming the image are presented in a structure (struct
    > +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.
    > +
    > +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::
    > +
    > + 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,
    > + };
    > +
    > + 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;
    > +
    > + priv = devm_kzalloc(dev, sizeof(*priv), GFP_KERNEL);
    > + if (!priv)
    > + return -ENOMEM;
    > +
    > + /*
    > + * do ioremaps, get interrupts, etc. and save
    > + * them in priv
    > + */
    > +
    > + mgr = fpga_mgr_create(dev, "Altera SOCFPGA FPGA Manager",
    > + &socfpga_fpga_ops, priv);
    > + if (!mgr)
    > + return -ENOMEM;
    > +
    > + platform_set_drvdata(pdev, mgr);
    > +
    > + ret = fpga_mgr_register(mgr);
    > + if (ret)
    > + fpga_mgr_free(mgr);
    > +
    > + return ret;
    > + }
    > +
    > + static int socfpga_fpga_remove(struct platform_device *pdev)
    > + {
    > + struct fpga_manager *mgr = platform_get_drvdata(pdev);
    > +
    > + fpga_mgr_unregister(mgr);
    > +
    > + return 0;
    > + }
    > +
    > +
    > +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.
    > +
    > +The programming sequence is::
    > + 1. .write_init
    > + 2. .write or .write_sg (may be called once or multiple times)
    > + 3. .write_complete
    > +
    > +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,

    at most long;

    > +if the whole bitstream is not immediately available then the core code will
    > +buffer up at least this much before starting.
    > +
    > +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.
    > +
    > +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.
    > +
    > +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
    > +------------------------------------------------
    > +
    > +Some sample code::
    > +
    > + #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);
    > +
    > + /* 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;
    > +
    > + /*
    > + * 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) {
    > +
    > + info->sgt = [your scatter gather table]
    > +
    > + } 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) {
    > +
    > + info->firmware_name = devm_kstrdup(dev, firmware_name, GFP_KERNEL);
    > +
    > + }
    > +
    > + /* 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);
    > +
    > + /* 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);
    > +
    > +API for implementing a new FPGA Manager driver
    > +----------------------------------------------
    > +
    > +.. kernel-doc:: include/linux/fpga/fpga-mgr.h
    > + :functions: fpga_manager
    > +
    > +.. kernel-doc:: include/linux/fpga/fpga-mgr.h
    > + :functions: fpga_manager_ops
    > +
    > +.. kernel-doc:: drivers/fpga/fpga-mgr.c
    > + :functions: fpga_mgr_create
    > +
    > +.. kernel-doc:: drivers/fpga/fpga-mgr.c
    > + :functions: fpga_mgr_free
    > +
    > +.. kernel-doc:: drivers/fpga/fpga-mgr.c
    > + :functions: fpga_mgr_register
    > +
    > +.. kernel-doc:: drivers/fpga/fpga-mgr.c
    > + :functions: fpga_mgr_unregister
    > +
    > +API for programming a FPGA
    > +--------------------------
    > +
    > +.. kernel-doc:: include/linux/fpga/fpga-mgr.h
    > + :functions: fpga_image_info
    > +
    > +.. kernel-doc:: include/linux/fpga/fpga-mgr.h
    > + :functions: fpga_mgr_states
    > +
    > +.. kernel-doc:: drivers/fpga/fpga-mgr.c
    > + :functions: fpga_image_info_alloc
    > +
    > +.. kernel-doc:: drivers/fpga/fpga-mgr.c
    > + :functions: fpga_image_info_free
    > +
    > +.. kernel-doc:: drivers/fpga/fpga-mgr.c
    > + :functions: of_fpga_mgr_get
    > +
    > +.. kernel-doc:: drivers/fpga/fpga-mgr.c
    > + :functions: fpga_mgr_get
    > +
    > +.. kernel-doc:: drivers/fpga/fpga-mgr.c
    > + :functions: fpga_mgr_put
    > +
    > +.. kernel-doc:: drivers/fpga/fpga-mgr.c
    > + :functions: fpga_mgr_lock
    > +
    > +.. kernel-doc:: drivers/fpga/fpga-mgr.c
    > + :functions: fpga_mgr_unlock
    > +
    > +.. kernel-doc:: include/linux/fpga/fpga-mgr.h
    > + :functions: fpga_mgr_states
    > +
    > +Note - use :c:func:`fpga_region_program_fpga()` instead of :c:func:`fpga_mgr_load()`
    > +
    > +.. kernel-doc:: drivers/fpga/fpga-mgr.c
    > + :functions: fpga_mgr_load


    --
    ~Randy

    \
     
     \ /
      Last update: 2018-05-26 04:29    [W:6.732 / U:0.000 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site